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:

1. 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.
2. 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:

$
curl https://app.recurrente.com/api/checkouts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "X-ACCOUNT-ID: ac_123456"
$
$
curl https://app.recurrente.com/api/intents \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "X-ACCOUNT-ID: ac_123456"

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.

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

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -F "email=ana@example.com" \
>
  -F "full_name=Ana Perez" \
>
  -F "phone_number=+50255555555" \
>
  -F "name=Ana Perez" \
>
  -F "account_type=individual" \
>
  -F "withdrawals_schedule=daily" \
>
  -F "verification[tax_registration_document]=@/path/ana-tax-registration.pdf" \
>
  -F "verification[id_card_image]=@/path/ana-id-front.jpg" \
>
  -F "verification[id_card_image_back]=@/path/ana-id-back.jpg"

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.

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -F "email=owner@restaurant.example" \
>
  -F "full_name=Ana Perez" \
>
  -F "phone_number=+50255555555" \
>
  -F "name=Acme Restaurant" \
>
  -F "account_type=business" \
>
  -F "withdrawals_schedule=daily" \
>
  -F "verification[tax_registration_document]=@/path/acme-tax-registration.pdf" \
>
  -F "verification[company_patent]=@/path/company-patent.pdf" \
>
  -F "verification[commercial_patent]=@/path/commercial-patent.pdf" \
>
  -F "verification[company_representative_document]=@/path/legal-representation.pdf" \
>
  -F "verification[company_representative_id]=@/path/representative-id-front.jpg" \
>
  -F "verification[company_representative_id_back]=@/path/representative-id-back.jpg" \
>
  -F "bank_account[holder_name]=Acme Restaurant, S.A." \
>
  -F "bank_account[number]=1234567890" \
>
  -F "bank_account[bank_name]=Banco Industrial" \
>
  -F "bank_account[currency]=GTQ" \
>
  -F "bank_account[account_type]=checking" \
>
  -F "bank_account[is_preferred]=true"

Example: non-profit account

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -F "email=admin@foundation.example" \
>
  -F "full_name=Luis Garcia" \
>
  -F "phone_number=+50255555556" \
>
  -F "name=Example Foundation" \
>
  -F "account_type=non_profit" \
>
  -F "withdrawals_schedule=weekly" \
>
  -F "verification[tax_registration_document]=@/path/foundation-tax-registration.pdf" \
>
  -F "verification[articles_of_incorporation]=@/path/articles-of-incorporation.pdf" \
>
  -F "verification[company_representative_document]=@/path/legal-representation.pdf" \
>
  -F "verification[company_representative_id]=@/path/representative-id-front.jpg" \
>
  -F "verification[company_representative_id_back]=@/path/representative-id-back.jpg"

Update a connected account

You can update the public name and withdrawal frequency for a connected account:

$
curl -X PATCH https://app.recurrente.com/api/connected_accounts/ac_123456 \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Acme Restaurant Zona 10",
>
    "withdrawals_schedule": "weekly"
>
  }'

Manage bank accounts

To add another external bank account to a connected account:

$
curl -X POST https://app.recurrente.com/api/connected_accounts/ac_123456/bank_accounts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "holder_name": "Acme Restaurant, S.A.",
>
    "number": "1234567890",
>
    "bank_name": "Banco Industrial",
>
    "currency": "GTQ",
>
    "account_type": "checking",
>
    "is_preferred": true
>
  }'

To change the default bank account, update the desired bank account with is_preferred: true:

$
curl -X PATCH https://app.recurrente.com/api/connected_accounts/ac_123456/bank_accounts/ba_123456 \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "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:

$
curl -X POST https://app.recurrente.com/api/checkouts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "X-ACCOUNT-ID: ac_123456" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "currency": "GTQ",
>
        "amount_in_cents": 3000,
>
        "name": "Example product"
>
      }
>
    ]
>
  }'

Fund distribution

You can distribute funds between accounts using transfer_setups. Each element defines a transfer that Recurrente executes automatically once the payment completes successfully:

• recipient_id is 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.
• If you omit recipient_id, funds are transferred to your own account — useful for keeping a commission when the checkout is created on behalf of a connected account.
• Use purpose: "platform_commission" when the transfer is a commission paid by the child account to your platform. If you omit purpose, Recurrente uses fund_split and excludes it from commission invoicing.
• 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.

1
{
2
  "items": [
3
    {
4
      "currency": "GTQ",
5
      "amount_in_cents": 3000,
6
      "name": "Example product"
7
    }
8
  ],
9
  "account_id": "ac_123456",
10
  "transfer_setups": [
11
    {
12
      "amount_in_cents": 100,
13
      "recipient_id": "ac_789012",
14
      "purpose": "platform_commission"
15
    }
16
  ]
17
}

Daily commission invoicing

You can ask Recurrente to issue one daily DTE per currency for transfers marked as platform_commission 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:

$
curl -X PUT https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoicing \
>
  -H "X-SECRET-KEY: your_live_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "mode": "daily" }'

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:

$
curl https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoices \
>
  -H "X-SECRET-KEY: your_live_key"
$
$
curl https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoices/pci_ab12cd34 \
>
  -H "X-SECRET-KEY: your_live_key"

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:

$
curl -X PUT https://app.recurrente.com/api/connected_accounts/ac_123456/fee_collection \
>
  -H "X-SECRET-KEY: your_live_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "fees_collector": "application" }'

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:

$
curl https://app.recurrente.com/api/connected_account_fee_invoices \
>
  -H "X-SECRET-KEY: your_live_key"
$
$
curl https://app.recurrente.com/api/connected_account_fee_invoices/cafi_ab12cd34 \
>
  -H "X-SECRET-KEY: your_live_key"

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:

$
curl -X POST https://app.recurrente.com/api/refunds \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "X-ACCOUNT-ID: ac_123456" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "payment_intent_id": "pa_ab12cd34",
>
    "refund_application_fee": true
>
  }'

The default is false. This parameter only affects transfers with purpose: "platform_commission"; 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:

1
{
2
  "id": "a_con_123456",
3
  "event_type": "account_connection.create",
4
  "status": "active",
5
  "api_version": "2024-04-24",
6
  "created_at": "2026-06-17T18:00:00Z",
7
  "live_mode": true,
8
  "parent_account": {
9
    "id": "ac_parent",
10
    "status": "active",
11
    "name": "Your platform",
12
    "account_type": "business",
13
    "created_at": "2026-06-17T17:00:00Z",
14
    "creator_name": "Ana Perez",
15
    "creator_email": "ana@example.com",
16
    "tax_id": "1234567",
17
    "tax_name": "Your Platform, S.A.",
18
    "withdrawals_schedule": "daily",
19
    "onboarding_completed": true
20
  },
21
  "child_account": {
22
    "id": "ac_child",
23
    "status": "active",
24
    "name": "Connected merchant",
25
    "account_type": "business",
26
    "created_at": "2026-06-17T18:00:00Z",
27
    "creator_name": "Juan Perez",
28
    "creator_email": "juan@example.com",
29
    "tax_id": "7654321",
30
    "tax_name": "Connected Merchant, S.A.",
31
    "withdrawals_schedule": "daily",
32
    "onboarding_completed": true
33
  }
34
}

When events occur in a child account, you’ll receive webhooks with additional parameters:

• connected: true indicates the event was generated by a connected account
• account_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.