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. In both cases, you’ll use that child account ID in account_id when creating checkouts.

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 account using the account_id parameter:

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

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.

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.