Getting started

Prerequisites

Before starting, you will need the following:

  • Access to the Switcloud API sandbox
  • Access to the Switstack packages repository

Please contact Switstack sales or support if access is required.

Steps

Step 1: Create the estate

Begin by creating the estate (either manually or programmatically). The estate is used by both the payment backend and the payment application.

  • Manual setup: Log into the Switcloud admin frontend with organization administrator credentials. Create at least a Merchant, a Store, and a POI.
  • Programmatic setup: Estate management can be performed by calling the Switcloud REST APIs directly. See the Swagger documentation for details.

Info

We also provide a series of API packages to avoid calling raw REST APIs in your code and simplify development. We currently support Kotlin, Python, TypeScript and C++. Please contact us if you need access and/or if you need support for another language.

Step 2: Create the EMV Configuration

Once the estate is ready, create the EMV configuration required for a terminal (POI) to process transactions.

As with estate creation, this can be done via the frontend, through API packages, or by calling the APIs directly.

A POIConfig object must contain at least an EMVConfig (and its sub-elements). CAPKs, CRs, and BINs are optional and can be configured later.

Step 3: Implement the payment backend (can be merged with the payment app)

In this example architecture, the payment processing logic is split between:

  • a backend, responsible for creating Payments and retrieving Payment data after each transaction
  • a payment application, running on the device, which handles card processing.

The backend should:

  • Import the appropriate switcloud-api package
  • Authenticate as a basic user
  • Create a Payment, specifying the POI ID and POIConfig ID (required parameters)
  • Retrieve the Payment ID used throughout the transaction
  • Pass the Payment ID to the payment application

Step 4: Implement the payment application

Next, implement the payment application code that will run on the device (COTS or PCI-PTS).

Whether building new or integrating with existing code:

  • Import the switcloud-clt package (currently available for Kotlin)
  • Instantiate the SwitcloudClient class
  • Authenticate as a basic user
  • Perform card processing using the Payment ID from step 3 (see examples for more detail)
  • Notify the backend when the transaction is complete

Step 5: Retrieve payment data from the backend

Return to the backend side of the application.

Using the switcloud-api package (or by calling the APIs directly), retrieve the Payment details (encrypted card data) associated with the Payment ID used in steps 3 and 4.

Step 6: Test in a sandboxed environment

switstack provides sandboxed environments for development and testing. Use these environments to validate your integration before moving to production.