Connected Accounts
If you’re building a platform or marketplace, and you want to:
- Charge on behalf of someone else, or
- Share revenue with other accounts
Connected Accounts is for you.
With Connected Accounts you can charge on behalf of other accounts using your own API keys, without needing access to their API keys.
Two ways to connect accounts
You can work with Connected Accounts in two ways:
- Create and manage a new connected account from your platform. This is the recommended flow when your platform onboards the merchant, manages their data, and configures their bank account.
- Connect an existing Recurrente account. This flow is useful when the merchant already uses Recurrente and only wants to authorize your platform to charge on their behalf.
Both paths end with a child account connected to your account. Use that child ID in X-ACCOUNT-ID to work with its resources. Endpoints that already accept account_id, such as checkouts and transfers, keep it as an alias.
Work inside a connected account
Send your own platform key together with X-ACCOUNT-ID. The request is limited to resources belonging to that child, but it isn’t filtered by who created them:
The platform can therefore retrieve checkouts and intents it created for the child as well as records the child created with its own keys. The child sees all of its own resources without sending the header. A platform can’t select unrelated accounts or accounts connected only through a child.
Supported account types
Both the platform and an existing recipient account can be personal or business accounts. Connect an existing personal account with the invitation link in Settings → Connected accounts: its administrator selects that account and confirms the connection, without sharing API keys or creating a business account.
The account_type: individual accepted by POST /connected_accounts means an individual business account, not a personal account. That endpoint’s account-creation types are unchanged; use the invitation flow for existing personal accounts. Verification, processing limits, and money-movement restrictions still apply. Account-type support is separate from approval of the platform’s use case.
Create and connect an account by API
You can create a connected account managed by your platform with POST /api/connected_accounts. Recurrente creates the child account, connects it to your account, validates the required documents, and marks onboarding as completed.
If a connected account already exists for the same email, Recurrente reuses that account and updates the submitted data. tax_id and tax_name are extracted automatically from the tax registration document sent in verification[tax_registration_document]; you do not need to send them in the request.
Required documents
Each account type requires different files in verification:
Example: individual account
Example: business account
You can send bank_account in the same request to configure the external bank account that will receive withdrawals. Use GET /api/banks to see valid bank_name values.
The bank account goes through the same validation as the app form. Bank, currency, and account-type format rules run first, followed by a bank lookup through Nexa. A valid confirmed name replaces holder_name. If the bank reports the account as compromised, the request fails with 400 and errors.number without creating the connected account.
If Nexa is unavailable, the bank is unsupported, or the limit of 20 lookups per Recurrente account in 24 hours is reached, the supplied name is saved unconfirmed. When the bank cannot find the account, supplying holder_name also allows saving it unconfirmed, just like the form. Sandbox never queries the bank. Resubmitting an existing destination does not query it again.
When creating a new connected account, the lookup uses the parent account’s budget. Its answer is kept for one hour even if creation fails, so retries can reuse it. An existing connected account uses its own budget.
Banrural: checking means monetaria and savings means ahorro. For GTQ, checking accounts accept prefixes 0 or 3 (10 or 14 digits), while savings accounts accept 0 or 4 (10, 13, or 14 digits). A number starting with 4 submitted as checking still fails format validation before Nexa is queried; submit the account’s actual type. GET /api/banks lists banks, not their account-format rules.
Example: non-profit account
Update a connected account
You can update the public name and withdrawal frequency for a connected account:
Manage bank accounts
To add another external bank account to a connected account:
To change the default bank account, update the desired bank account with is_preferred: true:
To remove a bank account, use DELETE. Recurrente archives it and stops showing it in the API.
Connect an existing account
If the merchant already has a Recurrente account, you don’t need to create another account by API. Connect both accounts from the Recurrente UI by following these instructions.
Create a checkout for a connected account
Once accounts are connected, create checkouts on behalf of the child with X-ACCOUNT-ID. account_id in the request body remains a compatibility alias:
Platform commission (application fee)
To keep a commission on a connected account’s sale, send application_fee_amount (one-time payments, in cents) or application_fee_percent (subscriptions, a percentage of each invoice’s total, 0–100 with up to 2 decimal places) when creating the checkout on behalf of the child account:
When the payment completes, Recurrente transfers the commission from the child account’s balance to your platform’s. For subscriptions, the commission is transferred on every successful charge while the subscription is active. The commission can be as high as the net available amount after fees, FEL, and VAT, can be reversed on refunds with refund_application_fee, and is included in daily commission invoicing when the connection has it enabled.
The checkout serializes the commission back as application_fee_amount / application_fee_percent, alongside the full detail in transfer_setups (the commission appears there with purpose: "platform_commission").
Before application_fee_amount / application_fee_percent existed, the commission was declared by hand as a transfer_setups element with purpose: "platform_commission". That form is still accepted for compatibility and behaves identically, but it cannot be combined with the new parameters in the same checkout.
Fund distribution
To route funds to other accounts (destination model: your account is the merchant of record and you send part of the net to a connected account), use transfer_setups. Each element defines a transfer that Recurrente executes automatically once the payment completes successfully:
recipient_idis the ID of the Recurrente account that receives the funds (e.g.ac_789012) — not a bank account. Funds are credited to that account’s Recurrente balance, and from there follow its normal withdrawal flow.- For one-time payments send
amount_in_cents: a fixed amount transferred once. It can be as high as the net available amount after fees, FEL, and VAT. - For subscriptions send
amount_percent: a percentage of each invoice’s total (0–100, up to 2 decimal places), transferred on every successful charge while the subscription is active. At checkout creation we validate that the percentage fits within the net amount after fees, FEL, and VAT. If the subscription is cancelled, its recurring transfers are cancelled with it.
Daily commission invoicing
You can ask Recurrente to issue one daily DTE per currency for the platform commissions (application fees) that each connected account pays to your platform. Your platform has a general setting (daily or none), and each connection can override it. It only covers completed live transfers after enabled_at; it does not classify or invoice historical transfers.
Enable it with a live API key. Your platform must be ready to issue FEL through INFILE, and the connected account must have a verified tax ID and legal name:
Recurrente processes closed America/Guatemala days asynchronously. Each document sums the exact completed commissions for one day and currency; it does not move the principal again. List documents and reconcile each line to its source transfer:
The detail response exposes transfer_setup_id, transfer_id, source_id, source_type, and completed_at. The partner_commission_invoice.issued and partner_commission_invoice.failed webhooks signal the result; failed is only delivered when no further automatic retry is appropriate.
Sending { "mode": "none" } sets an override that closes the interval. Sending { "mode": "default" } removes the override and resumes inheriting the general setting. Recurrente still drains commissions completed before disabled_at and preserves every existing document and line. The issuing platform can continue reading that history after disconnecting the account; configuration still requires an active connection.
The platform pays payment fees
The equivalent of Stripe’s defaults.responsibilities.fees_collector = application is fees_collector: "application". For a live checkout your platform creates on behalf of a connected account, Recurrente credits the connected account without deducting processor and Recurrente fees, and debits those fees from your platform balance at the same time. The connected account still pays its own withholding and FEL fee. This applies only to charges in GTQ or USD; in other currencies the connected account pays its fees as usual.
Configure one connection with a live API key. Your platform needs a verified tax ID and fiscal name:
Use recurrente for normal connected-account fee responsibility, or default to remove the override and inherit your platform’s general setting. Responsibility is snapshotted on each paid charge; changing it never rewrites earlier payments.
Recurrente issues one daily DTE per currency to your platform for all fees it covered that day, even when they came from several connected accounts:
Detail lines include connected_account_id, intent_id, payment_id, processor_fee_in_cents, recurrente_fee_in_cents, and paid_at. The connected_account_fee_invoice.issued and connected_account_fee_invoice.failed webhooks report the fiscal result. Issuing the DTE never moves money again.
Processor and Recurrente fees are not returned to the platform when the charge is refunded. Their historical DTE remains unchanged.
Refund a connected account charge
Your platform can refund a child account’s payment intent with its own API key. Send refund_application_fee: true to also return that charge’s platform commissions to the child account:
The default is false. This parameter only affects the platform commission (transfers with purpose: "platform_commission", including those created with application_fee_amount / application_fee_percent); recipients keep completed fund-split transfers. Both the child account and the platform can send it, but a platform API key must allow money movement.
Recurrente reserves the balance and reverses platform commissions before requesting the processor refund. The request fails before that call if the platform already spent the commission or if the child account can’t cover the full refund. Pending one-time transfer setups are cancelled; for subscriptions, only the refunded invoice’s fulfillment is affected and the template for future charges remains active.
If a commission already belongs to a daily DTE, Recurrente allows the refund when every line in that document belongs to the same payment and voids the DTE after the processor confirms the refund. If the document also includes commissions from other payments, the request fails instead of voiding their fiscal coverage. A DTE void error after a confirmed refund is reported for operational follow-up and doesn’t undo the refund.
The response includes refund_application_fee and transfer_adjustments. Each reversal appears as a new transfer linked through reversal_of_id and refund_id; the original transfer is never edited or deleted. If the processor rejects the refund, Recurrente creates compensating movements and restores the transfer setups. A concurrent request receives 202 and doesn’t call the processor twice.
If the processor outcome is indeterminate, the refund remains pending with failure_reason: "provider_outcome_unknown". Recurrente keeps the reservation and movements, doesn’t retry automatically, and a later POST returns 422 with the refund_id; retrieve that refund and contact support to reconcile it before attempting another operation. This first version only supports full refunds, and a successful refund that affected transfer setups can’t later be voided.
Webhooks
When a child account connects to your account, Recurrente sends an account_connection.create webhook to your account. The payload includes the connection and both accounts:
When events occur in a child account, you’ll receive webhooks with additional parameters:
connected: trueindicates the event was generated by a connected accountaccount_id: "ac_123456"is the ID of the account that generated the event
You can use these fields to identify and process connected account events separately.