Revenue sharing payments to site hosts

Enable CPOs to share revenue and pay rental to site hosts

Overview

Charging Point Operators (CPOs) often place charging stations on property owned by site hosts such as shopping malls, parking lots, or private business premises. These partnerships typically involve financial agreements where the site host receives compensation through two main payment models:

  1. Revenue sharing - Site hosts receive a percentage of the charging revenue generated at their location
  2. Fixed rental payments - Site hosts receive periodic fixed payments for hosting the charging infrastructure

This guide demonstrates how to implement both payment models using Embed's payment infrastructure, allowing CPOs to efficiently manage payments to their site host partners.

Key features

  • Automated payouts to site hosts - Calculate and distribute funds to site hosts based on revenue shares or fixed rental payments
  • Flexible site hosts payout frequency - Configure daily, weekly, or monthly payouts to site hosts
  • Payment tracking - Monitor all transfers with comprehensive reporting

Roles and responsibilities

Your Platform

  • Onboard with Embed as a

    Platform account

  • Initiate onboarding of CPOs

  • Configure pricing for site host payout services

  • Technical integration with Embed's APIs to create and manage operating balance accounts, transfers, and financial reporting

CPO (Charging Point Operator)

  • Onboard with Embed as a

    Merchant account

  • Topup funds into their

    Standard Balance Account
    to cover site host payouts

  • Pay fees to your platform based on the pricing plan you've configured for site host payouts

Site Host

  • Get onboarded with Embed with a
    Operating Balance Account
  • Receive automatic payouts to their bank account based on revenue sharing or rental agreements

Payment process

1. CPO balance account funding

CPOs topup funds into their balance account to cover site host payments.

We recommend CPOs to keep a buffer in the balance account to cover any fees that may be deducted from the balance and ensure site hosts are paid on time.

2. Balance account transfers

Funds can be transferred from the CPO's standard balance account to the site host's operating balance account in two main ways:

Revenue sharing transfers

  • Calculated based on charging activity at the site host's location
  • Typically processed after charging sessions are completed and revenue is calculated
  • Can be triggered by API calls when revenue data is available

Recurring fixed payments

  • Used for rental agreements or fixed commission structures
  • Can be transferred at will based on the logic of your platform

Your platform is responsible for triggering the transfer of funds to the site host's operating balance account. At this moment, Embed does not offer a scheduled job or recurring payment mechanism.

3. Site host payouts

Funds in the site host's operating balance account are paid out to their bank account according to the configured payout frequency. This could be as often as daily or less frequently depending on the site host's preference.

The payout process is independent of the transfer process. Site hosts will only receive payouts if there is a positive balance in their operating balance account.

Depending on your pricing plan, you may charge CPOs a fee for each transfer or payout. Fees are automatically deducted from the CPO's balance account balance during the process, and allocated to the Platform account balance.

Integration guide

1. Set up Platform account

Embed Dashboard

  • Set up Platform account with Embed
  • Configure pricing plans for CPOs

2. Start CPO onboarding

Your Platform

or

Embed Dashboard

You can choose between starting CPO onboarding process through the UI or by using the Onboarding APIs. In both cases, you'll need to store the Merchant Account ID in your system to later retrieve balance account information and financial reporting associated with that merchant.

CPOs can only transfer funds to their own Standard Balance Account. The bank account used for topups needs to be the same one which is configured in the Merchant payout settings.

Required attributes

  • Name
    parentAccountId
    Type
    string
    Description

    Id of the platform to which the merchant belongs.

  • Name
    name
    Type
    string
    Description

    Merchant name

  • Name
    description
    Type
    string
    Description

    Merchant description

  • Name
    userFirstName
    Type
    string
    Description

    First name of primary contact for the merchant.

  • Name
    userLastName
    Type
    string
    Description

    Last name of primary contact for the merchant.

  • Name
    onboardingEmail
    Type
    string
    Description

    Email address of primary contact for the merchant.

Request

POST
/v2/legal-entity/onboardMerchantAccount
{
    "parentAccountId": "{{platformAccountId}}",
    "name": "EcoCharge CPO GmbH",
    "description": "CPO operating charging stations in multiple locations",
    "userLastName": "Smith",
    "userFirstName": "John",
    "onboardingEmail": "john.smith@ecocharge.com",
}

Response

{
    "accountId": "21210021c2855007efa2d657018",
    "walletId": "wal_merchant_123"
}

3. CPO goes through onboarding

Self-service via Embed

CPOs can onboard themselves by using the onboarding link sent to their email address. You can read more about the onboarding process here.

Pricing plan navigation

4. CPO sets up their bank account details

Your Platform

or

Self-service via Embed

To topup funds into their balance account, CPOs need to configure their bank account details which will be used to transfer funds to their balance account. This can be done by using the Payout page or the Payout configuration API.

Wallet funding details

5. Get balance account topup details for CPO

Your Platform

or

Self-service via Embed

CPOs can topup funds into their standard balance account by using the bank account details and payment reference specific to their balance account. These details can be obtained from the Embed Dashboard or using the Get Balance Account Topup Details API.

Required attributes

  • Name
    id
    Type
    string
    Description

    The CPO's standard balance account ID for which to retrieve topup details.

Request

GET
/v2/balance-account/getTopupDetails?id={{standardBalanceAccountId}}
No body

Response

{
    "iban": "NL91ABNA0417164300",
    "accountHolder": "Stichting Custodian Embed",
    "reference": "1234567890"
}

The topup reference must be included in the payment description when making a bank transfer to ensure the funds are correctly allocated to the CPO's balance account.

6. Onboard Site hosts with Operating Balance Accounts

Your Platform

You can create an operating balance account for a site host by using the Create Operating Balance Account API. Site host operating balance accounts are created with a specific CPO account ID provided as the parent. This allows you to track balance account activity and balances associated with each CPO-site host relationship.

Operating balance accounts go through automatic compliance checks to ensure the site host is eligible to receive payouts. You can expect an instant response if the operating balance account is created successfully.

Required attributes

  • Name
    name
    Type
    string
    Description

    Name for the balance account to help identify it.

  • Name
    currencyCode
    Type
    string
    Description

    Currency code for the balance account (e.g., "EUR").

  • Name
    externalReference
    Type
    string
    Description

    Your unique reference for this balance account. Allows you to identify the balance account and link it to an existing account in your system.

  • Name
    parentAccountId
    Type
    string
    Description

    Merchant Account ID of the CPO which will be sending payments to this site host.

  • Name
    operatingDetails
    Type
    object
    Description

    Details of the site host.

    Expand
  • Name
    payoutConfig
    Type
    object
    Description

    The site host's bank account details for receiving payouts.

    Expand

Request

POST
/v2/balance-account/createOperatingBalanceAccount
{
    "name": "ShoppingCenter GmbH Balance Account",
    "currencyCode": "EUR",
    "externalReference": "site_host_123",
    "parentAccountId": "{{merchantAccountId}}",
    "operatingDetails": {
      "operatingType": "BUSINESS",
      "details": {
         "companyName": "ShoppingCenter GmbH",
         "countryCode": "DE"
      }
    },
    "payoutConfig": {
      "iban": "DE89370400440532013000",
      "accountHolder": "ShoppingCenter GmbH",
      "payoutPeriod": "END_OF_MONTH"
    }
}

Response

{
    "id": "ba_operating_456",
    // ... other operating balance account details
}

7. Transfer funds to Site Host

Your Platform

You can transfer funds from the CPO's standard balance account to a Site Host's operating balance account using the Create Balance Account Transfer API. Two main payment models can be implemented:

Revenue sharing model

  • Calculate the site host's share based on charging session data
  • Transfer the calculated amount when charging sessions are processed
  • Include specific references to tie transfers to charging sessions

Recurring rental payments

  • Set up scheduled transfers for fixed amounts at regular intervals
  • Use descriptive references to identify the payment period
  • Create automated workflows to handle these recurring payments

Transfers are processed asynchronously, and you will receive a webhook notification when the transfer is completed.

Required attributes

  • Name
    sourceId
    Type
    string
    Description

    The CPO's standard balance account ID from which funds will be transferred

  • Name
    destinationId
    Type
    string
    Description

    The Site Host's operating balance account ID to which funds will be transferred

  • Name
    amount
    Type
    number
    Description

    Amount to transfer in minor units (e.g., cents)

  • Name
    currencyCode
    Type
    string
    Description

    Currency code for the transfer (e.g., "EUR")

  • Name
    description
    Type
    string
    Description

    Description of the transfer that will help you identify the transaction in reports

Optional attributes

  • Name
    merchantReference
    Type
    string
    Description

    Your unique reference for this transfer. For revenue sharing, you might include charging session IDs or period references.

Request

POST
/v2/balance-account/transfer
{
  "sourceId": "ba_standard_123",
  "destinationId": "ba_operating_456",
  "amount": 3750,
  "currencyCode": "EUR",
  "description": "Revenue share payment for charging sessions Feb 15-28, 2024",
  "merchantReference": "rev_share_feb_2024_p2"
}

Response

{
  "id": "bat_123456789", // Balance Account Transfer ID
  "status": "ACCEPTED",
  "responseMessage": "Transfer accepted for processing"
}

For recurring payments, we recommend implementing a scheduled job in your system that triggers these transfers automatically according to the agreed payment schedule. This ensures site hosts receive their rental payments on time without manual intervention.

8. Handling Balance Account Events

Your Platform

You will receive webhook notifications for various balance account events. These webhooks help you track the status of topups, transfers, and payouts. Make sure to configure your webhook endpoint in the Dashboard or via API to receive these notifications. Key events include TRANSACTION.BALANCE_ACCOUNT_TRANSFER.COMPLETED and TRANSACTION.PAYOUT_TRANSACTION.SETTLED.

See our Notifications documentation for more information on webhook event types and how to handle them securely.

Embed expects a 200 response status from your webhook endpoint. If we don't receive a 200 status, we'll retry the webhook for up to 24 hours.

9. Getting balance account and transaction information

Your Platform

To maintain a complete overview of all financial operations and their associated fees, you can use the Get Balance Account List API and Get Balance Account Details API to retrieve balance account information and transaction history.

Balance Account APIs

Use the Balance Account APIs to:

  • List all operating balance accounts associated with a CPO
  • Get detailed information about specific balance accounts
  • Check balance account balances
  • Track balance account statuses and payouts

Learn more about balance account management in our Balance Account APIs documentation.

Settlement Reports

Settlement Reports provide detailed financial breakdowns including:

  • All topups, transfers and payouts processed
  • Service fees charged per operation
  • Net amounts settled
  • Complete audit trail of financial operations

These reports are generated automatically when funds are paid out from Operating balance accounts

Learn more about settlement reporting in our Settlement of Funds documentation.

Get Balance Account List Request

GET
/v2/balance-account/getBalanceAccountList?type=OPERATING&parentAccountId=mac_123456789
No body

Get Balance Account List Response

[
  {
    "id": "ba_operating_456",
    "parentAccountId": "mac_123456789",
    "type": "OPERATING",
    "name": "ShoppingCenter GmbH Balance Account",
    "currencyCode": "EUR",
    "status": "ACTIVE",
    "externalReference": "site_host_123",
    "operatingDetails": {
      "operatingType": "BUSINESS",
       "details": {
         "companyName": "ShoppingCenter GmbH",
         "countryCode": "DE"
      }
    },
    "payoutConfig": {
      "iban": "DE89370400440532013000",
      "accountHolder": "ShoppingCenter GmbH",
      "payoutPeriod": "END_OF_MONTH"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "ba_operating_789",
    "parentAccountId": "mac_123456789",
    "type": "OPERATING",
    "name": "Office Park Ltd Balance Account",
    "currencyCode": "EUR",
    "status": "ACTIVE",
    "externalReference": "site_host_456",
    "operatingDetails": {
      "operatingType": "BUSINESS",
      "details": {
        "companyName": "Office Park Ltd",
        "countryCode": "UK"
      }
    },
    "payoutConfig": {
      "iban": "GB29NWBK60161331926819",
      "accountHolder": "Office Park Ltd",
      "payoutPeriod": "END_OF_WEEK"
    },
    "createdAt": "2024-01-20T14:45:00Z"
  }
]