Skip to content

What is payment orchestration? A guide for SaaS

Payment orchestration routes each payment to the right provider by country and currency, retries safely without double charges and keeps one ledger.

Payrudder team9 min read

Payment orchestration is a layer that sits between your billing system and several payment providers and decides, for each customer and each payment, which provider handles it, how failures are retried, and how the results are recorded in one place. For a SaaS company it means you can sell through more than one provider without writing a separate billing flow for each.

This guide explains why SaaS companies end up with more than one provider, what an orchestration layer actually has to do (routing, safe retries, reconciliation, migrations), whether to build or buy it, and how Payrudder approaches it.

Why a SaaS company uses more than one payment provider

Most companies start with one provider and stay there for years. The second provider usually arrives for one of these reasons:

  • Coverage. No provider covers every country, currency and payment method equally well. A provider that is strong in the US and EU may be a poor fit for customers paying in Turkish lira, and the other way round.
  • Local cards and habits. Customers in some markets pay more easily with a local provider that supports their local cards and payment options. iyzico’s control panel, for example, has a dedicated section for instalment and commission settings (iyzico help center).
  • Merchant of record vs payment processor. A merchant of record such as Paddle becomes the legal seller and handles sales tax, VAT and chargebacks for you; a payment processor leaves those with you. Many companies want an MoR for global sales and a cheaper processor for their home market. We cover that choice in detail in merchant of record vs payment processor.
  • Redundancy. If one provider freezes your account or has an outage, a second one keeps new sales possible.
  • Cost. Fees differ a lot by model. Paddle’s pay-as-you-go price is 5% + 50¢ per transaction with tax and chargebacks included (Paddle pricing); iyzico’s help center lists commission starting from 4.29% plus ₺0.25 per successful transaction for corporate sellers, with your actual rate in your control panel (iyzico help center). Those are not comparable one to one, because the MoR fee includes tax work, but they show why routing by market can matter.

The moment you have two providers, your billing code has to answer questions it never had to answer before.

What payment orchestration has to do

Job The question it answers What goes wrong without it
Routing Which provider does this customer use? Customers land on a provider that cannot charge their currency, or move silently when a rule changes
Ownership Who renews and retries this subscription? Your code and the provider both retry, and the customer is charged twice
Safe retries Can we retry this charge? A timeout is treated as a failure and the charge is sent again
Reconciliation Does our record match the provider’s? Paid invoices look unpaid, refunds go missing, reports add lira to dollars
Migration How do we move a customer to another provider? Two live subscriptions, or a gap with none

Routing rules: country and currency

The simplest useful routing rule looks at two things: the customer’s country and the subscription’s currency. For example:

  1. Country TR and currency TRY → iyzico
  2. Anything else → Paddle (the default)

Two design choices matter more than the rules themselves.

Decide once, store the answer. The provider should be chosen when the subscription is created and saved on it. If routing is recalculated on every renewal, editing a rule quietly moves existing customers to a provider where they have no saved card.

Validate rules against what each provider can do. A rule that sends GBP subscriptions to a provider that cannot charge GBP should fail when you save it, not on the first renewal.

Ownership: one engine per subscription

Providers differ in how much of the lifecycle they run. A merchant of record like Paddle typically runs renewals and retries failed payments itself. A processor like iyzico charges a card when asked and leaves the schedule and retries to you.

An orchestration layer has to know which is which and give every subscription exactly one owner for renewal and dunning. If both your scheduler and the provider retry a failed payment, you get two charges and an angry customer.

Retries and idempotency: never charge twice

Payments fail in an awkward way: sometimes you do not know whether they failed. The request times out, the connection drops, the worker crashes after the provider answered but before the answer was saved. Retrying blindly can charge the customer a second time. Giving up can leave a paid invoice marked unpaid.

The patterns that make retries safe:

  • A saga with a state table. The charge is one step in a persisted state machine (invoice, PDF, charge, receipt). Each transition is written before the next command is sent, so a crash resumes from a known state.
  • One idempotency key per attempt. Each charge attempt gets a deterministic key. If the same attempt is delivered twice, the provider (or your worker) recognises it and returns the first result instead of charging again. A new attempt after a real decline gets a new key.
  • Ask before you retry when the outcome is unknown. If a charge times out, the state becomes “payment unknown”, and the next step is to ask the provider for the status of that attempt, not to charge again.
  • Retry declines on a schedule, not in a loop. A declined card is retried after days, not seconds, and eventually marked uncollectible.

Reconciliation: one payment ledger

Each provider reports money in its own format, currency and timing. Orchestration needs one payment ledger: an append-only record of every charge, refund and dispute across providers, each row pointing at the provider’s own reference.

With that ledger you can reconcile: check that every paid invoice has a matching charge and every charge belongs to an invoice, and raise the differences instead of fixing them silently. Provider webhooks should be verified and then confirmed with the provider before they change anything, because a webhook is a hint, not proof. Reports should be split by provider, country and currency, and never add two currencies together without an explicit rate.

Migrating subscriptions between providers

Sooner or later you will want to move customers: a cheaper provider, a new market, a provider that closed your account. Card details cannot be copied from one provider to another, so a migration always involves the customer entering a payment method on the new provider’s form.

A safe migration is a saga too:

  1. Create the customer at the new provider and collect a payment method through its hosted form.
  2. Create the new subscription aligned with the end of the period the customer already paid for.
  3. Cancel the old subscription only after the new provider confirms.

The order is the whole point. If anything fails before step 3, the old subscription keeps running unchanged. The customer is never on two live subscriptions, and never on none.

Build vs buy

You can build payment orchestration yourself. Teams that do usually underestimate the parts after the happy path: the unknown outcome, the duplicated webhook, the migration, the reconciliation report finance asks for at month end.

Question Build in-house Use an orchestration layer
First provider Fast Similar effort
Second provider A second set of flows, webhooks and edge cases An adapter and a routing rule
Double-charge safety You design and test it Comes with the layer; check how it is tested
Reconciliation and reports Usually built late Part of the layer
Control and data location Full Depends on the vendor
Ongoing cost Engineering time A subscription fee

Building makes sense if payments are your product or you only ever need one provider. Buying makes sense if you want to ship your actual product and still sell through two providers.

How Payrudder does payment orchestration

Payrudder is a usage metering, subscription billing and payment orchestration platform written in Go. Its orchestration works like this:

  • Providers declare capabilities. Each adapter says what the provider does: owns renewal, owns dunning, calculates tax, hosts checkout, sends its own receipts, has a refund API, which currencies it can charge. Payrudder does the rest. Paddle (merchant of record) runs renewals and retries itself; for iyzico, Payrudder schedules charges and retries; a bank-transfer provider tells the customer where to pay and waits for confirmation. The sandbox uses a built-in simulator.
  • One owner per subscription, taken from the provider’s capabilities, so two engines never retry the same payment. Because Paddle sends its own receipts, Payrudder does not mail a second one for payments Paddle took.
  • Routing rules by customer country and currency: ordered, first match wins, one default, evaluated once when the subscription is created and stored on it. A rule pointing at a provider that cannot charge that currency is rejected on save.
  • Never charging twice: an orchestrated saga with a state table, deterministic command ids, one idempotency key per attempt, and an unknown outcome that asks the provider before anything is retried. This is tested with random-reply tests, payment-unknown scenarios and a message-broker restart in the middle of a month close.
  • A payment ledger with reconciliation against the invoices, provider webhooks that are verified and confirmed with the provider, and reports (revenue, MRR, unpaid) by provider, country and currency.
  • Moving subscriptions between providers without both being live at once.

An honest limit: the Paddle and iyzico adapters are written from the providers’ documentation and tested against recorded fixtures. They have not yet been run against the providers’ sandboxes. Treat them as built, not production-proven.

Read more on the payment orchestration feature page, or, if you sell from Türkiye to both local and international customers, the selling SaaS from Türkiye use case.

Summary

Payment orchestration is what turns “we use two providers” from a pile of special cases into one billing system: route by country and currency once, give each subscription one owner, make every charge attempt idempotent, ask before retrying an unknown outcome, keep one ledger, and migrate only after the new provider confirms.

Payrudder Cloud is in early access, priced by system usage, never by a share of your revenue. See pricing.

Still adding up usage in a spreadsheet at month end?

Payrudder meters usage, issues the invoice and collects through iyzico, Paddle or bank transfer.

Keep reading