A payment aggregator gives the merchant one integration across multiple providers. It consolidates those providers on one platform, and its interface abstracts the providers and the payment methods they offer.

That interface normalizes provider differences across the payment: initiation, request and response formats, transaction status, error codes, and webhook notifications. The platform also routes the payment, reconciles it, reports on it, and fails over to another provider.

On a payment request, the aggregator divides into three domains.

  • Checkout: interacts with the merchant and the shopper as the payment proceeds.
  • Orchestrator: selects a provider and routes the payment request to it.
  • Adaptor: translates the aggregator’s model into that provider’s API, and translates the response back into the model.

Checkout domain

Checkout is where the merchant integrates. It speaks with the shopper when the payment requires the shopper.

The merchant chooses one of three integrations by how much control it wants over the checkout process.

  • API: the merchant owns the checkout. The shopper pays on the merchant’s website or app. The merchant server calls the aggregator server.
  • UI component: the merchant owns the page or the app. The shopper pays in an embedded aggregator component. The merchant client calls the aggregator server.
  • Hosted checkout: the aggregator owns the page. The merchant sends the shopper there, and the shopper pays on that page. The aggregator frontend calls the aggregator server.

The shopper selects a payment method from the methods available for that payment. When the method needs details, the shopper supplies them, such as card details, a phone number, or a virtual payment address. The payment request carries the method and its details, the amount, the currency, the product, and the shopper. Checkout authenticates the caller, checks idempotency, and validates the request against the API contract.

The response is the outcome of this call, or an action for the shopper to complete. The action can be a redirect, an app switch, a QR code to scan or to display, or a one-time password. The merchant or the aggregator presents the action, depending on the integration the merchant uses.

Orchestrator domain

Orchestrator is where the business rules sit. The request reaches this domain only after checkout has authenticated the caller and validated the request. The orchestrator decides whether to call a provider, which provider to call, and whether to retry. It also decides what checkout does next. The merchant and the shopper remain on the checkout edge. The provider API stays behind an adaptor.

Three tasks cover the usual work, and each one feeds the next.

  • Transaction screening: the orchestrator screens the payment for risk, fraud, and compliance. The screen uses predefined rules or a pre-trained model. If the screen rejects the payment, the orchestrator returns that result to checkout, and no provider is called.
  • Data enrichment: the orchestrator adds the screening results to the request, and any further data points that routing uses.
  • Provider selection: the orchestrator selects the provider from the merchant configuration and the data points on the request. It can choose only a provider the merchant is configured to use.

When a provider must be called, the orchestrator sends the request to that provider’s adaptor. The adaptor returns an internal result. From that result, the orchestrator chooses the next step and returns it to checkout. The next step is an action for the shopper to complete, or the outcome of this call.

Adaptor domain

Adaptor handles the outbound call to a provider and the inbound webhook from that provider. It translates the aggregator’s canonical model into the provider’s interface, and it translates the response back into the canonical model. Provider fields, credentials, and error codes stay inside the adaptor. Adding a provider, or updating a live one, does not spill into checkout or the orchestrator.

An ideal framework for the adaptor domain should hold the effort of each integration steady as providers are added and as live providers are upgraded. Four features are common to that framework.

  • Shared boilerplate: the framework supplies functions an integration would otherwise copy. Connection handling, cryptography, and serialization are three of those functions. Connection handling covers an HTTPS API, SOAP, or file exchange. Cryptography covers request signing, field encryption, and callback verification. Serialization covers JSON, XML, or a form body.
  • Isolated mapping: each provider’s mapping stands apart from every other mapping. The mapping converts the canonical model into that provider’s interface and converts the response back. A change to one mapping stays inside that mapping.
  • Connection versioning: the framework can run more than one version of a provider’s connection at the same time. One merchant can remain on the current version while another moves to the next. Each version keeps its own connection behavior until the older version is retired.
  • Flexible grouping: the framework can place providers into different deployable units. Conway’s law observes that a system mirrors the communication structure of the organization that builds it. A team groups the providers it owns into one unit and releases that unit on its own cycle.