Operational Best Practices

Reliable operations begin before the first transaction. Provider, payment flow, and notification configurations must be continuously reviewed, tested, and monitored.

This guide provides recommendations for platform operators and integration teams. For detailed instructions, refer to the guides provided at each stage.

Prepare your operation

Before configuring the platform:

• define who will be allowed to administer users, PSPs, flows, and integrations;
• grant only the access required for each role;
• keep credentials and Secret Keys in a secrets manager;
• separate sandbox and production configurations, credentials, data, and URLs;
• identify the countries, currencies, and payment methods to be used;
• confirm the contracted services and available credentials with each PSP.

caution

Do not share credentials by email or messaging apps, store them in source code, or record tokens, personal data, or card data in logs.

Follow the configuration sequence

Use this order to avoid incomplete dependencies:

1. Register and review providers under PSPs, following the PSP registration guide;
2. Configure credentials, countries, payment methods, and fees;
3. Create routing under Payment flow, following the payment flow guide;
4. Review every path and activate one flow for each payment method;
5. Under Integration, protect the Secret Key and configure the URL described in the notification guide;
6. Run test transactions and confirm both responses and notifications.

Use View to inspect a flow without the risk of changing it. Before saving an edit, confirm the selected merchant and payment method.

info

Only one flow can remain active for each payment method. Without an active flow, transactions for that method are not processed.

Validate data before saving

Area	What to review
PSP	Contracted and active provider, valid credentials, and supported countries
Fees	Percentages, fixed amounts, minimum amounts, currencies, and PayOut
Flow	Descriptive name, Yes and No outputs, balancer percentages totaling 100%, and a PSP at the end of every path
Payment	Merchant, amount, currency, country, payment method, and required fields
Integration	Public URL, HTTPS, 2xx response, checksum validation, and idempotency

Do not assume that a newly registered PSP is already able to receive payments. It must be configured and included in the corresponding active flow.

For card payments, use only approved components and refer to PCI and Non-PCI payment processing. Never use real cards in test environments.

Apply changes safely

1. Record the purpose, owner, and change window;
2. Review the current state before starting an edit;
3. Whenever possible, prepare and validate an inactive flow;
4. Confirm every path, provider, and credential;
5. Activate the change during the planned period;
6. Run a test transaction for every affected payment method;
7. Confirm the initial result and notification delivery;
8. Monitor subsequent transactions and maintain a rollback plan.

warning

Changing or disabling an active flow affects subsequent transactions. Do not make changes without confirming that another valid flow can be activated in case of failure.

Monitor operations

Continuously monitor:

• transaction volume and statuses by payment method;
• increases in declines or technical failures by PSP;
• provider response times and downtime;
• attempts made through alternative providers;
• webhook HTTP errors, latency, and downtime;
• duplicate, delayed, or unprocessed notifications;
• the validity of credentials, contracts, and HTTPS certificates.

The initial payment response is not always final. Update orders only after validating the response or notification, and process events idempotently.

Prevent and resolve common errors

Symptom	Likely cause	Recommended action
Payment is not processed	There is no active flow for the payment method	Review the corresponding tab and activate a valid flow
PSP does not appear in the flow	Registration, credentials, fees, or compatibility are incomplete	Review the contracted country, currency, and payment method
Flow cannot be saved	An output is disconnected, a path has no PSP, or percentages do not total 100%	Complete every path and adjust the percentages
PSP rejects the configuration	The credential is invalid or the service is not enabled	Validate the data with the PSP without exposing it in support tickets
Payment is routed to the wrong PSP	Conditions or priority do not match the expected rule	View every path and test boundary values
Update is not received	The URL is missing, unreachable, or returning an error	Test the endpoint, HTTPS, and the 2xx response
An update is applied more than once	The consumer is not idempotent	Track events by using the received identifiers
Token payment fails before reaching the PSP	The token is invalid, has been removed, or has no valid association	Request another token or perform a new secure capture

When investigating a failure, use the transaction and event identifiers. Do not copy Secret Keys, credentials, PANs, or security codes into support tickets, logs, or support tools.

Operational checklists

Before a change

• I confirmed the merchant, environment, and payment method;
• I reviewed the PSPs, credentials, fees, and compatibility;
• I validated every flow path and alternative provider;
• I prepared the tests and a rollback plan;
• I communicated the change window and owner.

After a change

• I confirmed which flow is active;
• I ran representative test transactions;
• I checked the selected PSP and returned status;
• I confirmed notification delivery and validation;
• I monitored failures, declines, and latency after activation.

During operations

• I investigated unusual changes in volume or status;
• I checked PSP and webhook failures;
• I confirmed that each notification was processed only once;
• I reviewed access and removed unnecessary permissions;
• I kept credentials, contracts, and certificates up to date.