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. In both cases, you’ll use that child account ID in custom_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:

Type	Documents
`individual`	`tax_registration_document`, `id_card_image`, `id_card_image_back`
`business`	`tax_registration_document`, `company_patent`, `commercial_patent`, `company_representative_document`, `company_representative_id`, `company_representative_id_back`
`non_profit`	`tax_registration_document`, `articles_of_incorporation`, `company_representative_document`, `company_representative_id`, `company_representative_id_back`

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 custom_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"
>       }
>     ],
>     "custom_account_id": "ac_123456"
>   }'

Parameter	Description
`custom_account_id`	The ID of the child connected account that will receive the payment
`transfer_setups`	Optional. Configuration for distributing funds between accounts

Fund distribution

You can distribute funds between accounts using transfer_setups:

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

Webhooks

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.