Payment Defaults & Flows

Now that you're familiar with Organizations, Accounts, and have set up your Connections, you're ready to process payments. In MoneyHash, there are two primary ways to initiate payments, depending on how much control you need:

1. Payment Defaults

Whenever you create a payment without specifying a Flow ID, MoneyHash automatically consults your Payment Defaults. This lookup checks which payment methods are available for the relevant currency and payment operation in your Account, then determines which Connection (i.e., payment provider) should process the payment.

By configuring Payment Defaults, you gain a quick, straightforward way to ensure each transaction is routed to the correct provider—no custom flow required. This is often enough if you have only a few connections or don't need granular logic around retries or dynamic method selection. However, if you prefer more advanced routing rules and detailed conditions, you can use Flow IDs instead (discussed below).

Limitations of Payment Defaults

The main drawback to Payment Defaults is their limited flexibility. You can't set specific conditions for when a payment method should appear or how it's displayed. Nor can you implement robust retry logic if a payment fails—there's no automatic fallback to a secondary provider. If you need that level of fine-tuning, you'll want to use Payment Flows, which offer detailed controls, branching logic, and support for multiple fallback scenarios.

2. Payment Flows

Payment Flows let you configure advanced payment logic in MoneyHash without constantly modifying your codebase. Rather than relying on a simple default, you can precisely define how your checkout process behaves under different circumstances, decide which payment methods to display, and determine the outcome if a payment fails or succeeds.

Dynamic Checkout

By setting up a Flow, you can tailor which payment methods your customers see based on any number of factors—like currency, the buyer's country, or metadata in the payment request. You can also control the order in which these methods appear and even customize the user interface for each method. This means you can optimize conversions by displaying only relevant options to each customer, all without needing to redeploy code every time you tweak a setting.

Routing Rules

Once a customer selects a payment method, Routing Rules kick in. These rules act as a decision tree, evaluating properties like payment instrument type, IP address, region, risk score, or custom fields you pass along. Based on these criteria, the Flow forwards the payment to the most appropriate connection, allowing you to handle scenarios where one provider might be cheaper or more reliable for certain currencies or regions.

In addition, you can specify exactly what happens in success or failure cases. For instance, if the payment fails at Provider A, you might automatically retry with Provider B, or if it succeeds, you can trigger a notification or post-processing step. This level of configurability ensures you don't have to alter your application code to implement changes—simply update the Flow in MoneyHash, and your checkout logic adapts immediately.

Flow Evaluation

Flow Evaluation in MoneyHash happens in three stages: Payment Methods, Payment Method Selection (Payment Processing), and Fallback. Each stage determines what the user sees, which routing actions are taken, and how final decisions are made.

1. Payment Methods Stage

When you first create a payment, the Flow evaluates the set of conditions you created in the Dynamic checkout section (like currency, country, user IP, or custom fields) to decide:

• Which payment methods to show (and which to hide)
• In what order those methods appear
• Which icons or UI elements to display for each method

Think of this as the "checkout customization" phase. The Flow tailors the visible payment methods based on real-time context, so customers only see relevant or allowed options.

2. Payment Method Selection (Payment Processing)

Once the user picks a payment method, the Flow starts a detailed evaluation called a Flow Run. During this process:

• Method Matching: The chosen payment method is matched against any Routing Rules in your Flow that cover that method type.
• Trigger Evaluation: The Flow checks each trigger in a top-down order. When a trigger's conditions are met, the Flow enters that trigger's sequence—a set of routing actions that might create transactions, apply additional checks, or move the payment to different providers.
• Sequence Execution: Within a sequence, more conditions can appear, chaining logic until the payment either succeeds, fails, or requires another action. Once all relevant actions in the sequence are complete, the Flow Run ends.

It's possible for multiple transactions or provider handoffs to occur in a single Flow Run if your routing rules specify retries or complex logic.

3. Fallback

If, after checking all triggers, none of them evaluate to "true" for the selected payment method, the Flow defaults to your Payment Defaults. In other words, the system reverts to whatever provider or configuration you set up as a basic fallback, ensuring that the payment can still go through if no advanced rule applies.

By structuring Flow Evaluation in this way, MoneyHash lets you build a dynamic, adaptive checkout that can adjust in real time to user attributes, transaction details, and custom business rules—while always maintaining a reliable fallback option if no specific logic is triggered.

The default setting ensures the payment is routed to the correct processing provider based on your configurations. For example, if the customer selects Card as their payment method, the default setting ensures the payment is routed to your default card processing provider.