Skip to content

Processing payments

The Payment APIs and Switcloud Client components enable payment applications to manage EMV-compliant, in-store transaction flows.

This flow is designed to support flexibility in modern architectures — separating the backend orchestration from the device-side EMV processing while maintaining consistent transaction control.

Typical payment flow

The following sequence describes the high-level payment flow as represented in the architecture diagram:

switcloud-payment-flow.png

1️⃣ Create payment

The payment backend initiates the transaction by calling the Switcloud Payment API (POST /payments) to create a new Payment object.

→ The Switcloud Server returns a Payment ID.

2️⃣ Initiate payment

→ The backend sends the Payment ID to the Payment Application (running on the device). → The Payment Application calls the switcloud Client to start the transaction, passing the Payment ID. → The Switcloud Client automatically fetches any required EMV configuration and interacts with the local EMV L2 stack.

3️⃣ Perform payment

The card interaction is performed locally:

→ The Switcloud Client processes the transaction with the EMV L2 stack. → The Switcloud Client sends the Payment Data (encrypted) to the Switclout Server.

4️⃣ Complete payment

The Payment Application is notified the Payment is complete which in turn can notify its backend counterpart.

5️⃣ Retrieve payment data

The backend retrieves final transaction data (GET /payments/{id}), for:

→ Reconciliation → Reporting → Submission to the acquirer or payment gateway.

Key API objects

  • Payment: The primary object representing the transaction.
  • Payment ID: A unique identifier used to coordinate state between the backend, application, and Switcloud Client.
  • Payment Data: The encrypted EMV transaction results, available for backend consumption.

Key architectural benefits

  • Separation of Concerns: The device-side Payment Application handles card-present interaction, while the backend coordinates orchestration.
  • Consistent API Across Hardware: The same flow applies whether the device is a COTS Android device or a PCI-PTS terminal.
  • Offline Support: The Switcloud Client can queue transactions for deferred completion if connectivity is temporarily unavailable.
  • EMV Compliance: All EMV processing is performed using certified stacks (moka or terminal kernel).

Next steps for developers

  • See payment API reference
  • See switcloud client SDK docs
  • See example payment integration flows