Account

Get started with the Switch Platform.

Businesses are at the forefront of the Switch Platform. When starting out with the Switch Platform, properly setting up your business account can be crucial to your integration efforts. Learn more about API keys and environments as well as how to proceed regarding authentication, whitelisting, languages, and navigation.

Authentication

All requests to any Switch API use HTTPS basic auth. Get a quick overview of how to handle these authentication specifications.

API Keys and Environment

Find more about Processing API Keys and Merchant API Keys and how to use them when setting up requests through the TEST or LIVE environments.

Whitelisting

Consider Switch in your whitelisting practices.

Languages

Our APIs offer multiple language options. Learn how to enable them.

Navigation and Pagination

Understand how to filter and navigate responses.

Navigation and Pagination

Understand how to filter and navigate responses.

If you are a merchant, you can use our Merchant API to create sub-merchants. The main merchant is responsible for onboarding each individual sub-merchant and it can also label accounts, set the hierarchy and customize white label features for the corresponding sub-merchants.

Associated to your main business account you can create multiple users' accounts. Each user account should correspond to a staff member. Individual users can have different sets of permissions associated with the authorization group they belong to.

Merchant and Submerchant Accounts

Create your merchant account and onboard submerchants seamlessly.

Users and Authorization Groups

Make things easier on your team and distribute permissions that fit your operations.

Authentication

All requests to Switch APIs must use HTTPS. In our examples, we use curl, nonetheless any language-specific HTTPS request method or library will work. All requests to Switch API use HTTPS Basic Auth. If your library does not support it as a function, you can add the following header to your requests.

BASIC AUTHORIZATION
Authorization: Basic {credentials}

For requests from the server-side, {credentials} should be replaced with the base64 encoded string accountId:privateKey. For requests from the client-side, {credentials} should be replaced with the base64 encoded string publicKey:.

Never expose your Private key on the client-side!

Keep your transactions secure and your clients’ information safe.

If you are not using the correct authentication, you will receive a 401 HTTP error. Merchant server webhooks should use HTTPS and self-signed certificates are not accepted. During development, it might be helpful using a service such as ngrok to expose an HTTPS tunnel to your local environment.

API Keys and Environment

You can also find these account details on the Switch Dashboard Settings screen.

We recommend using the Switch Dashboard for ease of access and a user-friendly work environment. Contact our Support Team to enable this feature.

Merchant Keys and the Environment you set are essential for communicating with Switch throughout your Payment operation.

Different combinations between the Merchant API Keys or Processing API Keys and your Account ID grant Authentication in your requests. It is important to be well aware of when to use each of the Keys and how to gain access to them. If you have any trouble with these, please contact our Support Team.

Environments can be set to TEST or LIVE depending on where you are at with your operations. If you are looking to test new features or still going through onboarding, use TEST. When your operations are up and running, LIVE should be the standard.

  • Public key

    Used in requests coming from the client-side, to create Dynamic Forms and Instruments.
  • Account ID + Private key

    Used in requests coming from the merchant server, to create Charges, Payments, Reversals, and Refunds, as well as accessing Management APIs. This key SHOULD NEVER BE SHARED in client-side code.
  • Environment

    TEST or LIVE, corresponding to https://api-test.switchpayments.com/v2/ and https://api.switchpayments.com/v2/, respectively. The v2 part of the URL corresponds to API versioning.

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

Whitelisting

Consider Switch in your Whitelisting.

Contact our Support Team for the necessary IP addresses to configure whitelisting.

A whitelist ensures only administrator-approved IP’s get access to your system. Whitelists are not one-size-fits-all; administrators tailor-make whitelists based on their unique wants and needs.

Mind your approved list of IP addresses that have permission to access your domain, and add Switch in case it facilitates our interactions. Reserved for only trusted users, IP whitelisting is only set and updated by the administrator.

Languages

Switch’s APIs support calls in multiple languages. This means that you can set up the desired language to be applied in the responses. To do so, you only need to include the respective language code in the HTTP header Accept-Language.

In case the target language is not available, the response will be generated in the default en-US. The following table includes our currently available language options.

LanguageHeader
English (USA)Accept-Language: 'en-US'
Portuguese (Portugal)Accept-Language: 'pt-PT'
Portuguese (Brazil)Accept-Language: 'pt-BR'

Navigation and Pagination

When making requests to Switch APIs that might generate multiple pages of results, only the first page is presented by default. This is to ensure there is no decline in performance when handling substantial volumes of information.

If you intend to access responses from other pages, mind the following procedure using as an example the GET v1/merchants/{id}/children endpoint which fetches the list of sub-merchants associated with a specific merchant.

GET /v1/merchants/{id}/children

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/merchants/{id}/children

Production
https:/merchant-api.switchpayments.com/v1/merchants/{id}/children		List available sub-merchants.
Request Parameters
pageNumberRequired

The page you want to consider for your list of results.

REQUEST EXAMPLE
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/merchants/{id}/children?page=3?merchant_id=accountId -u accountId:APIKey
RESPONSE EXAMPLE
    {
       "collection": [
           {
               "account_id": "OkJ4tL0eJuItLfDzGjwnDxVr6xE5HJcXw8oUbvaUYMracs",
               "account_type": "test",
               "name": "Candy shop",
               "metadata": {
                   "address": "Braga"
               },
               "approved": true,
               "created_at": "2020-10-23T15:00:02.090528+00:00",
               "updated_at": "2020-10-23T17:45:52.942176+00:00",
               "whitelabel_settings": "63f6d61deacfe8579e6499d3b62b92b959ad335b5f931679"
           },
           {
               "account_id": "ofAB1Ec0LBEv8tXtKyZrBCVhMAMtiFIV9fO6SNAzNgDK51fLnov",
               "account_type": "test",
               "name": "test dispute",
               "metadata": {
                   "address": "place"
               },
               "approved": true,
               "created_at": "2020-10-08T09:56:09.071632+00:00",
               "updated_at": "2020-10-08T09:56:09.071658+00:00"
           },
           {
               "account_id": "cvG0nPy1QYpZx6VyNCrZ5DaxZVwqOxi2PS3RedeVuVrVzrrbE",
               "account_type": "test",
               "name": "Demo",
               "metadata": {
                   "address": "Porto"
               },
               "approved": true,
               "created_at": "2020-09-23T11:00:12.459745+00:00",
               "updated_at": "2020-09-23T11:00:12.459787+00:00"
           }
       ],
       "filters": {},
       "pagination": {
           "page": 3,
           "per_page": 30,
           "total_pages": 3,
           "total_items": 3
       }
    }

Merchant and Sub-Merchant Accounts

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

The main merchant is responsible for onboarding each individual sub-merchant. The onboarding process consists of creating a business account on behalf of the sub-merchant. 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 sub-merchants. When creating a merchant account, you can also register White Label 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 merchant id 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 for 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

Sub-merchants 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 sub-merchants include searching sub-merchants using their id's, making changes to existing sub-merchant Accounts and deleting sub-merchants. sub-merchants are children to merchant accounts. Therefore it is important to keep in mind that a sub-merchant 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

Sub-merchants for 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 two factor 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 quthorization 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

Next Steps

Now that you have gone through the Switch starting kit, head over to the Integrating with Switch to learn more about the integration patterns available and choose the one that best suits your needs.

Did not find what you are looking for?

Contact our support department.

Was this page helpful?