Skip to content

Getting started

Prerequisites

Before starting, the following:

  • Access to the switcloud API sandbox
  • Access to the switstack packages repository

Please contact switstack sales or support if access is required.

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: Import the switcloud API package of your choice (Kotlin, Python, TypeScript, or C++) into your estate management application or script. Authenticate as an org admin and create the required objects.

Info

Estate management can also be performed by calling the switcloud APIs directly. See the Swagger documentation for details.

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.