Payment Flow
The payment flow is the path every transaction takes until it reaches the provider that will process it. This is where you decide, for example, that payments in reais go to one provider and payments in pesos go to another, or that 70% of transactions go through one provider and 30% through another.
You build this path visually: add the conditions you need, connect them to one another, and finish by choosing the provider that should receive the payment.
How it works
Each flow belongs to a single payment method (credit card, debit card, PIX, transfer, or digital wallets). You can create as many flows as you want for the same method, but only one can be active at a time — the active one is the flow used for payments.
When a payment arrives, the platform runs through the active flow for that method, evaluates each condition, and routes the transaction to the provider at the end of the path.
If there is no active flow for the payment method, transactions using that method are not processed.
Before you start
For a provider to appear as an option while you build the flow, it must be:
- contracted and active on your account;
- set up with credentials;
- set up with fees for the country and payment method;
- available for the payment method you are configuring.
If a provider you expect is missing from the list, check these four points first. The provider list shown on the screen is built from what is enabled on your account.
The flows screen
Go to Payment flow in the menu. The screen shows tabs with the payment methods available on your account, and each tab lists the flows already created, with:
- Flow Name;
- Last Modification;
- the Edit and View actions and the toggle that activates or deactivates the flow.
Creating a flow step by step
1. Choose the payment method
Select the tab for the method you want to configure and click Create new flow.
The method is defined by the tab you started from and cannot be changed later. To configure another method, create a new flow from the matching tab.
2. Name the flow
Fill in the Flow Name field at the top of the screen. Use up to 100 characters and prefer names that identify the rule, such as "Credit card — Brazil" or "PIX with balancing".
If you leave the field empty, the platform generates a name automatically, such as "Payment flow 1".
3. Add the conditions
Use the buttons above the diagram to add conditions. Each button opens a window where you choose the values and, once you confirm with Add, a new block appears on the diagram.
You can combine as many conditions as you need, one after another.
4. Connect the blocks
Every condition has two outputs: Yes and No. Drag from each output to the next block to build the path.
- The Yes output defines what happens when the condition is met;
- The No output defines what happens when it is not met.
Every condition must have both outputs connected. If any path is left unconnected, the flow cannot be saved.
5. End with a provider
Every path in the flow must end in a PSP block — the provider that will process the payment. A flow with any path missing a provider at the end is not accepted.
6. Save
Click Save. If everything is correct, you return to the flow list and the new flow appears in the tab of the selected method.
If something is incomplete, a message tells you what needs to be fixed. See Messages you may encounter.
Available conditions
| Condition | What it does | Available for |
|---|---|---|
| Country | Routes the payment according to the transaction country | All methods |
| Currency | Routes the payment according to the currency | All methods |
| Card Brand | Routes according to the card brand | Credit card and debit card |
| Installments | Routes according to the number of installments | Credit card |
| Value | Routes according to the payment amount | All methods |
| Balancer | Splits payments between providers by percentage | All methods |
| PSP | Defines the provider that processes the payment (path end) | All methods |
About the Value condition
When setting up the Value condition, choose the operator (Greater than,
Greater or equal, Less than, Less or equal, Equal, or Not equal) and enter the
amount in the payment currency — for example, 100 for $100.00. There is no
need to convert it to cents.
About the Installments condition
Available for credit card only. Use it to send, for example, single-payment transactions to one provider and installment transactions to another.
Main provider and backup providers
You can chain providers so that, if the first one cannot process the payment, the platform automatically tries the next one.
To do this, connect the output of one provider block to the next provider block. The order of the connection defines the priority:
[ PSP A ] ──► [ PSP B ] ──► [ PSP C ]
main backup backup
In this example, every payment goes to PSP A first. If it cannot process the payment, the platform tries PSP B and then PSP C.
Splitting payments between providers
The Balancer distributes transactions between two or more providers according to the percentages you define.
- Click Balancer;
- Enter the percentage for each range and use Add more to create new ranges;
- Confirm with Add;
- Connect each range to the provider that should receive it.
The percentages must add up to exactly 100%, and the balancer must have at least two ranges. Each range must also end in a provider.
Practical examples
One provider per currency
[ Currency is BRL? ] ──Yes──► [ PSP A ]
└────────────No───► [ PSP B ]
Payments in reais go to PSP A; all others go to PSP B.
Provider with backups
[ Country is BR? ] ──Yes──► [ PSP A ] ──► [ PSP B ]
└───────────No───► [ PSP C ]
Payments from Brazil go to PSP A and, if it fails, to PSP B. Payments from other countries go to PSP C.
Percentage split
┌── 70% ──► [ PSP A ]
[ Balancer ] ─────┤
└── 30% ──► [ PSP B ]
70% of transactions are processed by PSP A and 30% by PSP B.
Combining conditions
[ Value greater than 500? ] ──Yes──► [ PSP A ] ──► [ PSP B ]
└────────────────No───► [ Balancer ] ─┬─ 50% ─► [ PSP A ]
└─ 50% ─► [ PSP C ]
Payments above 500 go to PSP A, with PSP B as backup. All others are split evenly between PSP A and PSP C.
Activating the flow
In the flow list, use the status toggle to activate or deactivate a flow. The status changes immediately and applies to the next transactions.
There can be only one active flow per payment method. If you save a new flow while another one is already active, the new flow is created as Inactive. To use it, deactivate the current flow first and then activate the new one.
Editing, viewing, and deleting
| Action | What happens |
|---|---|
| Edit | Opens the diagram for changes. On save, the same validations apply. |
| View | Opens the diagram for reference only, with no changes allowed. |
| Delete | Removes the flow and all of its conditions. This action cannot be undone. |
Changing or deactivating a flow that is active immediately affects the next transactions. Prefer to make changes on an inactive flow and activate it when it is ready.
What happens when a payment arrives
- The platform identifies the payment method of the transaction;
- It finds the active flow for that method on your account;
- It runs through the conditions, following the Yes or No path according to the payment data;
- When it reaches a balancer, it picks the range according to the configured percentages;
- When it reaches the provider, it checks that the provider is active and has valid credentials;
- It sends the payment to the provider. If backups are configured and the first one fails, it tries the next one in priority order.
Messages you may encounter
| Message | What to do |
|---|---|
It is necessary to select at least one condition for this PSP. | Add at least one condition before saving the flow. |
The flow must have both paths (yes and no) to be valid | A condition has one output unconnected. Connect both the Yes and No paths. |
The flow does not end with a PSP | A path does not reach a provider. End every path with a PSP block. |
Main PSP name must not be null | A provider block has no provider selected. Open the block and choose one. |
Active payment flow already exists for this payment method | Deactivate the current flow before activating the new one. |
The sum of the % must be equal to 100% | Adjust the balancer percentages so they add up to exactly 100. |
No PSP available for currency: ... | No provider on your account supports that currency. Choose another currency or contract a compatible provider. |
No PSP available for country: ... | No provider on your account supports that country. |
No PSP available with card flag: ... | No provider on your account accepts that card brand. |
Currency ... not supported by PSP: ... | The selected provider does not operate with that currency. Choose another provider or adjust the condition. |
Country ... not supported by PSP: ... | The selected provider does not operate in that country. |
Best practices
- Use names that identify the flow rule, not just numbers;
- Configure at least one backup provider for the most used paths;
- Build and review the flow while it is inactive, then switch it on;
- After activating, run a test transaction to confirm the behavior;
- When you contract a new provider, remember to edit the flows that should start using it.
Frequently asked questions
Can I have more than one flow for the same payment method?
Yes. You can keep several flows created, but only one can be active per payment method.
Can I change the payment method of an existing flow?
No. The method is set when the flow is created. For another method, create a new flow from the matching tab.
What happens if I deactivate every flow of a method?
Transactions using that method stop being processed. Always keep one active flow for each method you use.
Do I need to change the flow when I contract a new provider?
Yes. The provider becomes available as an option, but it only receives payments after being added to an active flow.
Why was my flow created as inactive?
Because another flow was already active for the same payment method. Deactivate the previous one and activate the new one.