Adapter Design Pattern

// The interface our own code has always spoken.
public interface PaymentProvider {
    Receipt charge(Money amount, Card card);
}

// What the vendor ships. A compiled jar — we cannot change a line of it.
public final class NorthPaySdk {
    public TxnResult submitTransaction(String pan, double dollars, String currencyCode) { /* … */ }
}

public final class NorthPayAdapter implements PaymentProvider {

    private final NorthPaySdk sdk;   // the adaptee — HELD, not extended

    public NorthPayAdapter(NorthPaySdk sdk) {
        this.sdk = sdk;
    }

    @Override
    public Receipt charge(Money amount, Card card) {
        // Every translation the vendor forces on us happens here, once.
        double dollars = amount.cents() / 100.0;

        TxnResult result = sdk.submitTransaction(
                card.pan(),
                dollars,
                amount.currency().code());

        // Their failures are return values; ours are exceptions. Translate that too.
        if (!"APPROVED".equals(result.status)) {
            throw new PaymentDeclined(result.reasonText);
        }
        return new Receipt(result.txnRef, amount, Instant.ofEpochSecond(result.epochSeconds));
    }
}

// Wiring — the only line in the codebase that knows NorthPay exists:
PaymentProvider provider = new NorthPayAdapter(new NorthPaySdk(apiKey));

// GoF also describes a CLASS adapter (`extends NorthPaySdk implements PaymentProvider`).
// Java has no multiple inheritance, the SDK class is final, and inheriting from a
// vendor type welds you to it — so the object adapter above is what people actually write.

from decimal import Decimal


class NorthPayAdapter:
    """Duck typing removes the NAME problem. It does not remove the SHAPE problem.

    If the vendor's method were also called `charge` and took the same arguments,
    Python would need no adapter at all — that is the honest answer, and it is why
    this pattern is less common here. But the mismatch below is about units,
    argument order and error style, and no amount of duck typing fixes those.
    """

    def __init__(self, sdk: NorthPaySdk) -> None:
        self._sdk = sdk

    def charge(self, amount: Money, card: Card) -> Receipt:
        result = self._sdk.submit_transaction(
            pan=card.pan,
            # Decimal, never float — money that round-trips through binary
            # floating point is how you end up one cent short at reconciliation.
            dollars=Decimal(amount.cents) / 100,
            currency_code=amount.currency,
        )

        if result.status != "APPROVED":
            raise PaymentDeclined(result.reason_text)

        return Receipt(
            reference=result.txn_ref,
            amount=amount,
            at=datetime.fromtimestamp(result.epoch_seconds, tz=timezone.utc),
        )


# Declaring the target as a Protocol gives you the compile-time check that duck
# typing otherwise costs you — mypy will now tell you if the adapter drifts:
#
#     class PaymentProvider(Protocol):
#         def charge(self, amount: Money, card: Card) -> Receipt: ...

#include <memory>
#include <stdexcept>

struct PaymentProvider {
    virtual ~PaymentProvider() = default;
    virtual Receipt charge(Money amount, const Card& card) = 0;
};

// Third-party, header-only, not ours to change.
class NorthPaySdk {
public:
    TxnResult submitTransaction(const std::string& pan, double dollars,
                                const std::string& currencyCode);
};

class NorthPayAdapter final : public PaymentProvider {
public:
    explicit NorthPayAdapter(std::shared_ptr<NorthPaySdk> sdk)
        : sdk_(std::move(sdk)) {}

    Receipt charge(Money amount, const Card& card) override {
        const double dollars = static_cast<double>(amount.cents()) / 100.0;

        TxnResult r = sdk_->submitTransaction(card.pan(), dollars, amount.currencyCode());

        if (r.status != "APPROVED") throw PaymentDeclined(r.reasonText);
        return Receipt{r.txnRef, amount, std::chrono::sys_seconds{std::chrono::seconds{r.epochSeconds}}};
    }

private:
    std::shared_ptr<NorthPaySdk> sdk_;
};

// C++ is the one language where the class adapter is genuinely idiomatic, because
// private multiple inheritance exists precisely for it:
//
//     class NorthPayAdapter : public PaymentProvider, private NorthPaySdk { … };
//
// The STL leans on this idea hard: std::stack and std::queue are CONTAINER
// ADAPTERS — they hold a std::deque and expose a completely different interface
// over it. Same pattern, standardised.

public interface IPaymentProvider
{
    Task<Receipt> ChargeAsync(Money amount, Card card, CancellationToken ct = default);
}

public sealed class NorthPayAdapter(NorthPaySdk sdk) : IPaymentProvider
{
    public async Task<Receipt> ChargeAsync(Money amount, Card card, CancellationToken ct = default)
    {
        // decimal, not double — the vendor chose double, and containing that
        // choice inside one class is a large part of why this adapter exists.
        var dollars = (double)(amount.Cents / 100m);

        var result = await sdk.SubmitTransactionAsync(card.Pan, dollars, amount.Currency.Code, ct);

        if (result.Status != "APPROVED")
            throw new PaymentDeclinedException(result.ReasonText);

        return new Receipt(result.TxnRef, amount, DateTimeOffset.FromUnixTimeSeconds(result.EpochSeconds));
    }
}

// Registered once, injected everywhere as the interface:
builder.Services.AddSingleton<NorthPaySdk>();
builder.Services.AddSingleton<IPaymentProvider, NorthPayAdapter>();

// A common wrong turn: reaching for an extension method instead.
//
//     public static Receipt Charge(this NorthPaySdk sdk, Money m, Card c) => …
//
// It compiles and it reads nicely, but an extension method CANNOT implement an
// interface — so NorthPaySdk still isn't an IPaymentProvider, and none of your
// existing call sites or test doubles work. You need the class.

// The target is a shape, not a declaration, so the adapter can be a plain object
// — or a factory function returning one.

export const northPayAdapter = sdk => ({
  async charge(amount, card) {
    // amount.cents is an integer on purpose; the vendor wants dollars.
    const dollars = amount.cents / 100

    const result = await sdk.submitTransaction(card.pan, dollars, amount.currency)

    if (result.status !== 'APPROVED') {
      throw new PaymentDeclined(result.reason_text)
    }

    return {
      reference: result.txn_ref,
      amount,
      at: new Date(result.epoch_seconds * 1000),   // seconds → milliseconds
    }
  },
})

const provider = northPayAdapter(new NorthPaySdk(apiKey))

// Two conversions above are classic JavaScript trip-hazards worth naming:
// snake_case → camelCase across the boundary, and Unix SECONDS → Date
// MILLISECONDS. Both are silent when you get them wrong: no error, just a
// receipt dated 1970 or a field that's permanently undefined.

package payments

// Go makes the constraint explicit: you cannot define a method on a type from
// another package. If northpay.SDK doesn't satisfy your interface, wrapping it
// is not one option among several — it is the only option the language gives you.

type Provider interface {
	Charge(amount Money, card Card) (Receipt, error)
}

type northPayAdapter struct {
	sdk *northpay.SDK
}

func NewNorthPay(sdk *northpay.SDK) Provider {
	return northPayAdapter{sdk: sdk}
}

func (a northPayAdapter) Charge(amount Money, card Card) (Receipt, error) {
	dollars := float64(amount.Cents) / 100

	res, err := a.sdk.SubmitTransaction(card.PAN, dollars, amount.Currency)
	if err != nil {
		return Receipt{}, fmt.Errorf("northpay: %w", err)
	}
	if res.Status != "APPROVED" {
		return Receipt{}, &DeclinedError{Reason: res.ReasonText}
	}

	return Receipt{
		Ref:    res.TxnRef,
		Amount: amount,
		At:     time.Unix(res.EpochSeconds, 0).UTC(),
	}, nil
}

// The standard library's neatest adapter is a function type:
//
//	type HandlerFunc func(ResponseWriter, *Request)
//	func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) { f(w, r) }
//
// That is the whole pattern in three lines — it adapts an ordinary function to
// the http.Handler interface, which is why you can pass a func to http.Handle.

interface PaymentProvider {
  charge(amount: Money, card: Card): Promise<Receipt>
}

class NorthPayAdapter implements PaymentProvider {
  constructor(private readonly sdk: NorthPaySdk) {}

  async charge(amount: Money, card: Card): Promise<Receipt> {
    const dollars = amount.cents / 100

    const result = await this.sdk.submitTransaction(card.pan, dollars, amount.currency)

    if (result.status !== 'APPROVED') {
      throw new PaymentDeclined(result.reason_text)
    }

    return {
      reference: result.txn_ref,
      amount,
      at: new Date(result.epoch_seconds * 1000),
    }
  }
}

// Structural typing means `implements` is a CHECK, not a requirement — anything
// with a matching `charge` already satisfies PaymentProvider. Write it anyway:
// it moves the error from the call site to the adapter, which is where you can
// actually fix it.

// Branded types stop the unit bug the adapter exists to contain, by making the
// two numbers different types that cannot be swapped by accident:
type Cents = number & { readonly __brand: 'Cents' }
type Dollars = number & { readonly __brand: 'Dollars' }
const toDollars = (c: Cents): Dollars => (c / 100) as Dollars