Marketplaces

Marketplaces allow merchants that operate as intermediaries between buyers and sellers to process payments and settle funds to sellers automatically and securely.

Related API reference

• Create a payment intent
• Confirm a payment intent
• Retrieve a payment intent
• List all payment intents

Create a marketplace account

Create the account from the Marketplace section in the ONVO Dashboard. There, you set the seller business name and the marketplace commission percentage, in addition to ONVO transaction fees and withholdings when applicable.

When the account is created, ONVO generates:

• An Account ID to identify the seller in transactions.
• An onboarding link so the seller can complete registration.

Seller onboarding

The onboarding link is unique per marketplace account. The seller must complete it to receive payments. During this process, they provide the IBAN accounts where settlements should be sent.

The link expires after 7 days. You can regenerate it from the marketplace account detail; when you do, the previous link expires.

Once onboarding is complete, the marketplace account is enabled to accept payments on its behalf.

Payment flow

Always use the API keys from the primary account, meaning the account that created the marketplace. Marketplace accounts do not have their own API keys.

Payment methods must also be created in the primary account.

1. Create a payment intent with the onBehalfOf attribute, using the seller's Account ID.

{
  "amount": 10000,
  "currency": "USD",
  "onBehalfOf": "ma502zv0d0127ebdp3zt27651"
}

2. Confirm the payment intent with the paymentMethodId.

{
  "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
}

3. If the charge succeeds, ONVO calculates ONVO fees, withholdings, and the marketplace commission on the gross amount.

Example for a 100.00 USD transaction:

Concept	Amount
Gross amount	100.00 USD
ONVO fee 3.5%	3.50 USD
Withholding 2%	2.00 USD
Net amount	94.50 USD
Marketplace commission 5%	5.00 USD
Amount settled to seller	89.50 USD

The marketplace commission is deposited into the primary account and the net amount is deposited to the seller.

Test and live mode

You can create marketplace accounts in test or live mode depending on the active Dashboard mode.

Accounts created in test mode only work with test keys. Accounts created in live mode only work with live keys. You cannot change an account's mode after it is created.