SwitchPay API (0.5.0)

Download OpenAPI specification:Download

This is the SwitchPay API documentation.

The goal of SwitchPay is to provide every single functionality over the REST API. Everything can be achieved programmatically so that features like automatic merchant onboarding can be effortlessly achieved with SwitchPay.

SwitchPay API uses standard HTTP methods and verbs to provide RESTful interface over different resources like payments. SwitchPay accepts form-encoded requests and responds with JSON payload with the following structure:

{
  "error": false,
  "data": {}
}

The error property indicates whether the request was successfully processed. The data property will contain the payload. In case of success it will be the resource created or fetched depending on the REST action invoked by the caller. In case of validation errors it will have a following structure:

{
  "error": true, // will be set to true to indicate error
  "data": [
    {
      "message": "\"email\" is not allowed to be empty", // The error message
      "path": [
        "email" // The path, property for which validation has failed
      ],
      "type": "string.empty", // The type of validation errors, in this example indicates that the provided string was empty (blank) whereas it shouldn't
      "context": {
        "label": "email",
        "value": "", // The value that was supplied in the request and is not valid
        "key": "email" // The attribute key for which validation failed
      }
    }
  ]
}

In case validation for multiple property would fail the data will contain the number of objects one per each property that failed to pass a validation.

List of validation error types

  • alternatives.match - No alternative matched the input due to specific matching rules (regex).
  • any.custom - A custom validation error.
  • any.required - A required value wasn't present.
  • any.unknown - A value was present while it wasn't expected.
  • number.integer - The number is not a valid integer.
  • number.max - The number is higher than the limit.
  • number.min - The number is lower than the limit.
  • number.negative - The number was positive.
  • number.positive - The number was negative.
  • object.unknown - An unexpected property was found in the object.
  • string.alphanum - The string doesn't only contain alphanumeric characters.
  • string.base - The input is not a string.
  • string.domain - The string is not a valid domain name.
  • string.email - The string is not a valid e-mail.
  • string.empty - When an empty string is found and denied by invalid values.

Files API

Allows to upload files used for KYC operations.

Create new file.

Use this request to create a new file.

File can be used to obtain signed upload URL which allows customer to upload KYC documents.

Request Body schema: application/json
file_name
required
string

Uploaded file name.

mime_type
required
string
Enum: "image/png" "image/jpeg" "application/pdf"

Uploaded file mime type.

Responses

201

File was successfully created.

403

User is not authorized to access this resource.

422

Request validation error.

post /files
https://api.switchpay.cc/files

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "file_name": "document.pdf",
  • "mime_type": "application/pdf"
}

Response samples

Content type
application/json

Retrieve file details.

Retrieve file details.

path Parameters
id
required
string
Example: ea8d74a4-fd46-4ddd-a141-49555a37900b

File ID.

Responses

200

OK

404

Resource not found.

get /files/{id}
https://api.switchpay.cc/files/{id}

Response samples

Content type
application/json

Create file download URL.

Create file download URL.

path Parameters
id
required
string
Example: ea8d74a4-fd46-4ddd-a141-49555a37900b

File ID.

Responses

201

OK

404

Resource not found.

Secret Key Sets API

Generate and recycle secret API keys.

List all secret keys for a branch

Use this request to fetch all secret keys (including private and publishable) for a branch.

query Parameters
branch_id
string
Example: branch_id=613d88e5-e2bd-4e18-aa6d-8535f051db9d

The ID of a branch for which return the secret keys.

Responses

200
get /identity/secret_key_sets
https://api.switchpay.cc/identity/secret_key_sets

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {
    }
}

Generate new secret keys set.

Use this request to generate new set of secret keys for a branch.

The keys set consists of exactly 4 keys:

  • Secret live - this key starts with sk_live and should be kept secret and used by the backend services in live environment.
  • Secret test - this key starts with sk_test and should be used by backend services in sandbox environment.
  • Publishable live - this key starts with pk_live and can be shared with a front-end and used in live environment.
  • Publishable test - this key starts with pk_test and can be shared with a font-end and used in sandbox environment.

The difference between secret and publishable key are permissions. Secret key is granted all permissions while publishable is restricted. You don't want to use the same key in backend-to-SwitchPay and fontend-to-SwitchPay communication. Your backend is considered safe environment and can do anything whereas front-end is considered as hostile environment and has limited access rights.

Request Body schema: application/json
branch_id
required
string

The identifier of a branch for which create a set of secret keys.

Responses

201

Secret key set was successfully created.

403

User is not authorized to access this resource.

422

Request validation error.

post /identity/secret_key_sets
https://api.switchpay.cc/identity/secret_key_sets

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "branch_id": "613d88e5-e2bd-4e18-aa6d-8535f051db9d"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {
    }
}

Sessions API

Allows exchanging user's email and password for JWT access token.

Create new session.

This API authenticates regular user by email and password. It responds with access token that can be used to interact with SwitchPay REST API.

Depending on the user role, access token contains appropriate permissions.

Request Body schema: application/json
email
required
string

The email of the user to authenticate.

password
required
string

The password of the user to authenticate.

audience
required
string

The domain for which given access key is being generated.

Responses

201

User was authenticated and session was successfully created.

403

User authentication failed.

422

Request validation error.

post /identity/sessions
https://api.switchpay.cc/identity/sessions

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "email": "user@domain.com",
  • "password": "thesecretpassword",
  • "audience": "example.com"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {
    }
}

Tokens API

Allows exchanging secret or publishable key for JWT access token.

Create new access token.

This API authenticates API client by secret or publishable key. Once authenticated, it responds with an access_token that can be used to authorise further SwitchPay REST API requests.

Depending on the key type, appropriate permissions are assigned and stored within access token.

Request Body schema: application/json
secret
required
string

Key used to authenticate API client.

audience
required
string

The domain for which given access key is being generated.

Responses

201

Token created.

403

User authentication failed.

422

Request validation error.

post /identity/tokens
https://api.switchpay.cc/identity/tokens

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secret": "sk_test_cd8b5654444e111424000bb6d94d8c52bd0edbda135d361d62d9d81232685baa",
  • "audience": "example.com"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {
    }
}

Users API

Manage organisation users and log-in credentials.

Create new user.

Use this request to create a new user for your organisation.

Users can be assigned to a branch or created globally. Requires appropriate access rights in order to create new user or assign it to specific branch.

Request Body schema: application/json
email
required
string

Email of the user to create. Email is used to authenticate user and must be unique.

full_name
required
string

Name of the user

password
required
string

Password for the new user.

branch_id
string

The identifier of a branch to which assign the user. When not set creates a global user, not assigned to any organisation.

Responses

201

User was successfully created.

403

User is not authorized to access this resource.

422

Request validation error.

post /identity/users
https://api.switchpay.cc/identity/users

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "email": "user@domain.com",
  • "full_name": "John Doe",
  • "password": "topsecretpass",
  • "branch_id": "613d88e5-e2bd-4e18-aa6d-8535f051db9d"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {
    }
}

Bank Accounts API

Create bank account.

Creates bank account for merchant.

Bank account is required:

  • to payout money
  • to satisfy Stripe Connected Account KYC requirements
path Parameters
merchantId
required
string
Example: ea8d74a4-fd46-4ddd-a141-49555a37900b

SwitchPay merchant ID.

Request Body schema: application/json
account_owner_name
required
string

Bank account owner full name.

account_owner_type
required
string
Enum: "individual" "company"

Account owner type.

bank_name
required
string

Bank name in which account has been created.

currency
required
string

The three-letter ISO currency code. See supported currencies guide.

country_code
required
string

The two-letter ISO country code.

account_number
required
string

Valid bank account number.

bank_routing_number
string

Bank routing number.

type
string
Enum: "company" "individual"

Bank account type.

Responses

201

Bank account created.

404

Resource not found.

422

Request validation error.

post /merchants/{merchantId}/bank-accounts
https://api.switchpay.cc/merchants/{merchantId}/bank-accounts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "account_owner_name": "John Doe",
  • "account_owner_type": "individual",
  • "bank_name": "Bank of America",
  • "currency": "USD",
  • "country_code": "US",
  • "account_number": "000123456789",
  • "bank_routing_number": 111000000,
  • "type": "company"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": false,
  • "data":
    {