Overview

This document describes Add-On Mart adapter requirements.

Adapter is a service that bridges PortaOne infrastructure with specific external service provider. It is deployed alongside Add-On Mart services, translates standardized Add-On Mart requests into the provider’s API, and returns responses in the format expected by Add-On Mart.

Architecture

Implementation options

• gRPC service (containerized): synchronous gRPC calls, we do not currently support asynchronous flows (e.g., streaming or webhooks).
• Cloud function — see How to create new cloud function for Add-on Mart (high-level instruction) (with children pages)

Requirements

• The adapter should follow general PortaOne Guidelines for writing, packaging and provisioning containerized applications/services.
  • The Error propagation and Health probes sections of the guidelines are mandatory.
• The adapter must implement corresponding gRPC interfaces to align with Add-On Mart infrastructure. We cannot integrate an adapter, unless it fully implements these interfaces.

Interfaces

• Interfaces are organized by service type (e.g., cpe, t2s, paymentProcessors, sms, templates).
  Each service type defines:

  • adapterService.proto — RPC methods

  • adapterTypes.proto — request/response models and enums

    • adapterTypes.proto includes field-level conventions (currency units, timestamps formats, etc.) as the field description.

• If you do not use gRPC (e.g., Cloud Function), you must mirror these interfaces exactly:

  • Same method names

  • Same field names, types, and enums

  • JSON payloads that correspond exactly to the protobuf messages

• All RPCs defined in adapterService.proto are mandatory, unless explicitly marked as optional in comments. If your external service cannot support a specific method, or part of a method, the adapter must return a gRPC error with status code UNIMPLEMENTED (12), along with a clear message describing what functionality is not available.

Implementation examples

Here are examples of adapter implementation.

• CPE adapter

• Templates adapter

• Payment-processor adapter

• Text-to-Speech adapter

• SMS adapter