The sub-account feature allows you to handle the sharing between several accounts or not of each transaction amount received.

Requirements

• A verified Marketplace as main account
• At least one sub-account associated to your main account

Context

It's common to see services with a marketplace business model. A marketplace is a platform where several service providers are registered and offer their goods or services. Each of these platforms work differently but the payment processing looks a like. For each product sold on the platform, the marketplace owner has a percentage on the amount and the rest of the amount is for the service provider. FedaPay gives you all you need to register service provider, handle payments, transfer assets and so much more.

Create a transaction with shared commissions

We consider here that the marketplace knows the FedaPay accounts reference of its service providers. This is compulsory to specify the commission to be shared between service providers and the main FedaPay account of the marketplace.

When creating a transaction, the application must specify on the amount to collect, the part due to third parties meaning here the service providers. Most of the time a transaction involves one service provider. But it's possible to have more than one.

Below an example of transaction creation request with shared commission for a FedaPay service provider sub-account.

curl -X POST \
  https://sandbox-api.fedapay.com/v1/transactions \
  -H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "description" : "Transaction for [email protected]",
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "callback_url" : "https://maplateforme.com/callback",
        "customer" : {
            "firstname" : "John",
            "lastname" : "Doe",
            "email" : "[email protected]",
            "phone_number" : {
                "number" : "+22997808080",
                "country" : "bj"
            }
        },
        "sub_accounts_commisssions": [
          {
            "reference": "acc_xxxxxxxxx",
            "amount": 1500
          }
        ]
      }'

/* Replace YOUR_API_SECRET_KEY by your API secret key */
  \FedaPay\FedaPay::setApiKey("YOUR_API_SECRET_KEY");
  
  /* Specify whenever you are willing to execute your request in test or live mode */
  \FedaPay\FedaPay::setEnvironment('sandbox'); //or setEnvironment('live');
  
  /* Create the transaction */
  \FedaPay\Transaction::create(array(
    "description" => "Transaction for [email protected]",
    "amount" => 2000,
    "currency" => ["iso" => "XOF"],
    "callback_url" => "https://maplateforme.com/callback",
    "customer" => [
        "firstname" => "John",
        "lastname" => "Doe",
        "email" => "[email protected]",
        "phone_number" => [
            "number" => "+22997808080",
            "country" => "bj"
        ]
    ],
    "sub_accounts_commisssions" => [
      [
        "reference" => "acc_xxxxxxxxx",
        "amount" => 1500
      ]
    ]
  ));

const { FedaPay, Transaction } = require('fedapay')
  
  /* Replace YOUR_API_SECRET_KEY by your API secret key */
  FedaPay.setApiKey("YOUR_API_SECRET_KEY");
  
  /* Specify whenever you are willing to execute your request in test or live mode */
  FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
  
  /* Create the transaction */
  const transaction = await Transaction.create({
    description: 'Description',
    amount: 2000,
    callback_url: 'https://maplateforme.com/callback',
    currency: {
        iso: 'XOF'
    },
    customer: {
        firstname: 'John',
        lastname: 'Doe',
        email: '[email protected]',
        phone_number: {
            number: '97808080',
            country: 'BJ'
        }
    },
    sub_accounts_commisssions: [
        {
            reference: 'acc_xxxxxxxxx',
            amount: 1500
        }
    ]
  });

acc_xxxxxxxxx is the FedaPay sub-account reference of the service provider.

So when the transaction will be approved, the amount of 1,500 XOF will be transferred to the service provider sub-account and the remain to the main account.

Verify a transaction and its shared commissions

On the main account FedaPay dashboard, you can check on a transaction with shared commission by looking at the transaction details.

Invite a service provider sub-account to your FedaPay account from your dashboard

You can invite a service provider to your FedaPay account. Just click on the Marketplace menu.

This menu is available only if you have validated your account as a Marketplace. Click on Invite a business then fill the form with the service provider information.

Once the invitation accepted, the service provider will join your FedaPay account and you will be able to share commissions.

Automate new sub-accounts adding

It's possible to add new sub-accounts to your FedaPay account using our API. Meaning you can automate the adding. We help you to collect and verify information on your service providers to meet the requirements of the KYC and compliance matter.

curl -X POST \
  https://sandbox-api.fedapay.com/v1/auth/sub_account_invitations \
  -H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "email" : "[email protected]",
        "full_name" : "Jonh Doe"
      }'