Merchant

Onboard new merchants seamlessly.

Merchants are at the center of the Switch Platform. All the decisions we make about our Platform Components, processes, and features revolve around them. When setting up your operation with Switch, Merchant settings define your territory. Through the Merchant API, you can create new Merchants and Submerchants, and keep an eye on permissions and Authorization Groups.

API Keys

Through the API Keys resource you can browse, delete, and make changes to existing API Keys. You can also create new ones.

GET /v1/merchants/{merchantId}/keys

Get API Keys corresponding to a specific Merchant.

Result Parameter

collectionArray

A list that contains all the API Key objects.


idString

Unique identifier for the API Key.


activeBoolean

Whether the Key is currently active.


authorization_groupJSON Object

The Authorization Group associated with the key.


descriptionString

The Key's description.


keyString

The API Key.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/keys -u accountId:apiKey
RESULT: HTTP 200
{
"collection": [
"...",
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"active": true,
"authorization_group": null,
"description": "Default Keys",
"key": "3eva1vGdMdg0GNLiArtNcXL4WgQtL4sJLCplXzfFCyKRZJCQYSIPUewelaJJdQ4"
},
"..."
]
}

POST /v1/merchants/{merchantId}/keys

Create API Keys.

Request Parameter

activeBoolean

Whether the Key is currently active or not.


descriptionString

The Key's description.


authorization_groupString

The Authorization Group associated with the Key.

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/keys -u accountId:apiKey -d '{
"active": true,
"description": "Default Keys",
"authorization_group": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954"
}'
Result Parameter

idString

Unique identifier for the API Key.


activeBoolean

Whether the Key is currently active or not.


authorization_groupJSON Object

The Authorization Group associated with the Key.


descriptionString

The Key's description.


keyString

The API Key.

RESULT: HTTP 201
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"active": true,
"authorization_group": null,
"description": "Default Keys",
"key": "3eva1vGdMdg0GNLiArtNcXL4WgQtL4sJLCplXzfFCyKRZJCQYSIPUewelaJJdQ4"
}

It is not possible to create API Keys 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/merchants/{merchantId}/keys -u accountId:apiKey -d '{
"active": true
}'
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": {
"description": [
"This field is required."
],
"authorization_group": [
"This field is required."
]
}
}

API Key ID

It is possible to search API Keys through their respective id's. The API Key id is also a resource to consider when you are looking to make changes to existing API Keys and the ways in which you identify them.

GET /v1/merchants/{merchantId}/keys/{apiKeyId}

Get details on the Merchant API Key using its id.

Result Parameter

idString

Unique identifier for the API Key.


activeBoolean

Whether the Key is currently active or not.


authorization_groupJSON Object

The authorization group associated with the Key.


descriptionString

The Key's description.


keyString

The API Key.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/keys/{apiKeyId} -u accountId:apiKey
RESULT: HTTP 200
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"active": true,
"authorization_group": null,
"description": "Default Keys",
"key": "3eva1vGdMdg0GNLiArtNcXL4WgQtL4sJLCplXzfFCyKRZJCQYSIPUewelaJJdQ4"
}

PATCH /v1/merchants/{merchantId}/keys/{apiKeyId}

Make changes to the Merchant API Key id.

Request Parameter

activeBoolean

Whether the Key is currently active.


descriptionString

The Key's description.


authorization_groupString

The Authorization Group associated with the Key.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/keys/{apiKeyId} -u accountId:apiKey -d '{
"active": true,
"description": "Default Keys",
"authorization_group": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954"
}'
Result Parameter

idString

Unique identifier for the API Key.


activeBoolean

Whether the Key is currently active.


authorization_groupJSON Object

The Authorization Group associated with the Key.


descriptionString

The Key's description.


keyString

The API Key.

RESULT: HTTP 200
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"active": true,
"authorization_group": null,
"description": "Default Keys",
"key": "3eva1vGdMdg0GNLiArtNcXL4WgQtL4sJLCplXzfFCyKRZJCQYSIPUewelaJJdQ4"
}

DELETE /v1/merchants/{merchantId}/keys/{apiKeyId}

Delete a Merchant API Key using its id.

REQUEST
$ curl -vX DELETE https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/keys/{apiKeyId} -u accountId:apiKey


Merchant and Submerchant Accounts

As we have seen, the Merchant Account holds information that is fundamental to your communications with Switch and the success of your transactions. Setting up a Merchant Account with extensive information that mirrors your business is important to keep your payment operation up and running.

The main Merchant is responsible for onboarding each individual Submerchant. The onboarding process consists of creating a Merchant Account on behalf of the Submerchant. The main Merchant needs only to be aware of the parent account and register its id.

Merchants accounts can be set to TEST or LIVE. You can choose how to label the accounts and the hierarchy set between Merchant and Submerchants. When creating a Merchant Account, you can also register Whitelabel settings, which grant for the customization of your workspace in case you are using the Switch Dashboard.

Merchants

The available operations on regards to Merchants include searching for Merchants by id and creating Merchants from scratch. It is also possible to make changes to existing Merchant accounts, as well as delete them.

POST /v1/merchants

Create Merchant.

Request Parameter

account_typeString

The type of the account ("live" or "test").


nameString

The Merchant's name.


parentString (Optional)

If we are creating a Submerchant, set the parent's account ID here.

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/merchants -u accountId:apiKey -d '{
"account_type": "test",
"name": "ACME Corp.",
"parent": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954"
}'
Result Parameter

account_idString

Unique identifier for the Merchant.


account_typeString

The type of the account ("live" or "test").


nameString

The Merchant's name.


childrenArray

Submerchants of this account.

RESULT: HTTP 201
{
"account_id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"account_type": "test",
"name": "ACME Corp.",
"children": []
}

It is not possible to create Merchants 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/merchants -u accountId:apiKey -d '{
"name": "ACME Corp."
}'
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": {
"account_type": [
"This field is required."
]
}
}

Merchant ID

It is possible to get details on Merchants using their respective id's. The Merchantid is also a resource to consider when you are looking to make changes to existing Merchant accounts.

GET /v1/merchants/{id}

Get Merchant details using its respective id.

Result Parameter

account_idString

Unique identifier for the Merchant.


account_typeString

The type of the account ("live" or "test").


nameString

The Merchant's name.


childrenArray

Sub-merchants of this account.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{id} -u accountId:apiKey
RESULT: HTTP 200
{
"account_id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"account_type": "test",
"name": "ACME Corp.",
"children": []
}

PATCH /v1/merchants/{id}

Make changes to Merchant details using its id.

Request Parameter

nameString

The Merchant's name.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/merchants/{id} -u accountId:apiKey -d '{
"name": "ACME Corp."
}'
Result Parameter

account_idString

Unique identifier for the Merchant.


account_typeString

The type of the account ("live" or "test").


nameString

The Merchant's name.


childrenArray

Submerchants of this account.

RESULT: HTTP 200
{
"account_id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"account_type": "test",
"name": "ACME Corp.",
"children": []
}

DELETE /v1/merchants/{id}

Delete Merchant.

REQUEST
$ curl -vX DELETE https://merchant-api.switchpayments.com/v1/merchants/{id} -u accountId:apiKey

Submerchants

The available operations on regards to Submerchants include searching Submerchants using their id's, making changes to existing Submerchant Accounts and deleting Submerchants. Submerchants are children to Merchant accounts. Therefore it is important to keep in mind that a Submerchant always has a parent Merchant Account.

GET /v1/merchants/{id}/children

Result Parameter

collectionArray

A list that contains all the Merchant objects.


account_idString

Unique identifier for the Merchant.


account_typeString

The type of the account ("live" or "test").


nameString

The Merchant's name.


childrenArray

Submerchants of this account.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{id}/children -u accountId:apiKey
RESULT: HTTP 200
{
"collection": [
"...",
{
"account_id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"account_type": "test",
"name": "ACME Corp.",
"children": []
},
"..."
]
}

Users and Authorization Groups

The way you set up Authorizations Groups and Users, defines the dynamics of your team when using Switch’s APIs. Make sure you pay close attention to your Users, keep the permissions up to date, and if you need any help feel free to contact our Support Team.

Users

The available operations for the Users resource are GET, and POST.

GET /v1/merchants/{merchantId}/users

Result Parameter

collectionArray

A list that contains all the User objects.


idString

Unique identifier for the user.


emailString

User's email address.


last_loginString

Date of last login.


nameString

User's name.


global_permissionsJSON Object

Global permissions for the User.


merchants_permissionsJSON Object

Merchant's permissions for the User.


own_merchants_permissionsJSON Object

Merchant's permissions only for Authorization Groups linked to the User.


tfa_via_app_enabledBoolean

Whether the user has TwoFactor Authentication enabled for this account.


merchantsArray

Merchants the User has access to.


authorization_groupsArray

Authorization Groups linked with this User.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/users -u accountId:apiKey
RESULT: HTTP 200
{
"collection": [
"...",
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"email": "john@acme.com",
"last_login": "2019-11-07 11:52:11",
"name": "John Doe",
"global_permissions": {},
"merchants_permissions": {
"756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954": {
"com.switchpayments.dashboard.transactions_read": true,
"com.switchpayments.dashboard.refund": true
}
},
"own_merchants_permissions": {
"756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954": {
"com.switchpayments.dashboard.transactions_read": true,
"com.switchpayments.dashboard.refund": true
}
},
"tfa_via_app_enabled": false,
"merchants": [],
"authorization_groups": null
},
"..."
]
}

POST /v1/merchants/{merchantId}/users

Request Parameter

emailString

The User's email address.


nameString

The User's name.

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/users -u accountId:apiKey -d '{
"email": "john@acme.com",
"name": "John Doe"
}'
Result Parameter

idString

Unique identifier for the User.


emailString

User's email address.


last_loginString

Date of last login.


nameString

User's name.


global_permissionsJSON Object

Global permissions for the User.


merchants_permissionsJSON Object

Merchant's permissions for the User.


own_merchants_permissionsJSON Object

Merchant's permissions only for Authorization Groups linked to the User.


tfa_via_app_enabledBoolean

Whether the user has Two Factor Authentication enabled for this account.

RESULT: HTTP 201
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"email": "john@acme.com",
"last_login": null,
"name": "John Doe",
"global_permissions": {},
"merchants_permissions": {},
"own_merchants_permissions": {},
"tfa_via_app_enabled": false
}

It is not possible to create Users 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/merchants/{merchantId}/users -u accountId:apiKey -d '{
"name": "John Doe"
}'
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": {
"email": [
"This field is required."
]
}
}

User ID

The available operations for the User ID resource are PATCH and DELETE.

PATCH /v1/merchants/{merchantId}/users/{userId}

Request Parameter

permissionsJSON Object

Key value object of the permissions the User should or should not have.


authorization_groupsArray (Optional)

List of Authorization Groups id the User should be associated with (it will remove any Groups not present in this list, if the User is associated with them).

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/users/{userId} -u accountId:apiKey -d '{
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
},
"authorization_groups": [
"756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"674ae7bhn83927h5cf6hu87d8hfoiuhiudspwef8429jlsdf"
]
}'
Result Parameter

idString

Unique identifier for the User.


emailString

User's email address.


last_loginString

Date of last login.


nameString

User's name.


global_permissionsJSON Object

Global permissions for the User.


merchants_permissionsJSON Object

Merchant's permissions for the User.


own_merchants_permissionsJSON Object

Merchant's permissions only for Authorization Groups linked to the User.


tfa_via_app_enabledBoolean

Whether the User has Two Factor Authentication enabled for this account.


merchantsArray

Merchants the User has access to.


authorization_groupsArray

Authorization Groups linked to this User.

RESULT: HTTP 200
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"email": "john@acme.com",
"last_login": "2019-11-07 11:52:11",
"name": "John Doe",
"global_permissions": {},
"merchants_permissions": {},
"own_merchants_permissions": {},
"tfa_via_app_enabled": false,
"merchants": [],
"authorization_groups": null
}

DELETE /v1/merchants/{merchantId}/users/{userId}

REQUEST
$ curl DELETE https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/users/{userId} -u accountId:apiKey

Authorization Groups

The available operations for the Authorization Groups resource are GET, and POST.

GET /v1/merchants/{merchantId}/authorization-groups

Result Parameter

collectionArray

A list that contains all the Authorization Group objects.


idString

Unique identifier for the Authorization Group.


typeString

The Authorization Group's type.


nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups -u accountId:apiKey
RESULT: HTTP 200
{
"collection": [
"...",
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"type": "merchant",
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
},
"..."
]
}

POST /v1/merchants/{merchantId}/authorization-groups

Request Parameter

nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups -u accountId:apiKey -d '{
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
}'
Result Parameter

idString

Unique identifier for the Authorization Group.


typeString

The Authorization Group's type.


nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

RESULT: HTTP 201
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"type": "merchant",
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
}

Create Authorization Group without required fields

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups -u accountId:apiKey -d '{
"name": "Analysts Permissions"
}'
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": {
"permissions": [
"This field is required."
]
}
}

Authorization Group ID

The available operations for the Authorization Group ID resource are GET, PATCH, and DELETE.

GET /v1/merchants/{merchantId}/authorization-groups/{authorizationGroupId}

Result Parameter

idString

Unique identifier for the Authorization Group.


typeString

The Authorization Group's type.


nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups -u accountId:apiKey
RESULT: HTTP 200
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"type": "merchant",
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
}

PATCH /v1/merchants/{merchantId}/authorization-groups/{authorizationGroupId}

Request Parameter

nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

REQUEST
$ curl -vX PATCH https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups/{authorizationGroupId} -u accountId:apiKey -d '{
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
}'
Result Parameter

idString

Unique identifier for the Authorization Group.


typeString

The Authorization Group's type.


nameString

The Authorization Group's name.


permissionsJSON Object

The Authorization Group's permissions.

RESULT: HTTP 200
{
"id": "756ae7bdc3390050cf6648fb819ac1c4de02f4d15b278954",
"type": "merchant",
"name": "Analysts Permissions",
"permissions": {
"refund": true,
"routing_management": true,
"read_processing_api_keys": false
}
}

DELETE /v1/merchants/{merchantId}/authorization-groups/{authorizationGroupId}

REQUEST
$ curl -vX DELETE https://merchant-api.switchpayments.com/v1/merchants/{merchantId}/authorization-groups/{authorizationGroupId} -u accountId:apiKey