The last payment integration ever needed

By integrating with Switch, you get access to every present and future payment method, as well as all the tools required to run a professional and comprehensive payments operation.

Switch is a Platform-as-a-Service, which means that every operation available through our Dashboard can also be performed using an API.

Processing Transactions with Switch

There are several steps to take full advantage of Switch's processing capabilities.

Not all the steps are required to process payments, but it is good to have the full picture before making your integration options.


  1. Display a Form - The form through which the customer chooses a payment method can be created by you, but if you use Switch's Dynamic Forms or REST Integration to do it, your form will adapt to future payment methods without requiring additional development.
  2. Create Charges and Instruments - These are the minimum steps to process a transaction using Switch.
  3. Instrument flows - Handle methods that require redirection or displaying references.
  4. Event Handling - How your server will keep track of transactions.
  5. Capturing funds later - For recurring or auth-capture methods.

Elements of a Transaction

Every Transaction, regardless of the payment method, has the same elements:

  1. Charge - the merchant’s intent to make a money transfer. This is the step where the payment method and provider is chosen and configured by the merchant.
  2. Instrument - the customer authorises the transfer, by sending payment details.
  3. Payment - the fund transfer per se.
  4. Refund (for refundable payment methods) - returning the funds to the customer.

Instruments from different payment methods have specific properties that define how they can be used:

Property Description
Captured on creation A Payment is created automatically when the customer creates the Instrument
Recurring Multiple Payments can be created from a recurring instrument
Refundable Refunds can be created
Redirect The customer must be redirected to an external page to complete the transaction. This process is handled automatically by the Dynamic Forms and JS lib
Reference The customer will be shown a reference to push the funds to

Documentation Structure

Switch Integration:

  • Overview - General and platform-wide concepts
  • Dynamic Forms - The recommended integration to start processing with Switch
  • REST Integration - Lower level integration for other use-cases
  • Transaction Flows - Additional integration steps to support specific transaction flows, such as references, redirection, auth-capture, recurring payments and refunds.
  • Handling Events - Integrating transaction lifecycle events with your system

API Reference

  • Client Library - Complete API reference for the Client Library, used for dynamic forms creation.
  • Processing API - Complete API reference for the Processing REST API, used for processing payments.
  • Management API - Complete API reference for the Management API, used for dashboard operations.

Merchant Keys and Environment

You can find the following account details on the Dashboard Settings screen:

  • 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 and Refunds, as well as accessing management APIs. This key should never be shared in client-side code.
  • Environments - TEST or LIVE, corresponding to and, respectively. The v2 part of the URL corresponds to API versioning.


All requests to Switch APIs must use HTTPS.

In our examples we use curl, but any language specific HTTPS request method or library will work.

All requests to Switch API use HTTPS Basic Auth. If your library doesn't support it as a function, add the following header to your requests

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: (notice the final :).

Never expose your private key on the client-side!

If you are not using the correct authentication, you’ll receive a 401 or 403 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.


If you find any error or missing feature in these docs, please contact support.

results matching ""

    No results matching ""