Platforms and Marketplaces

Platform Implementation Models

Use this guide if you are a SaaS platform or marketplace providing surcharging to sub-merchants, and each sub-merchant is the merchant of record for their own transactions. If your platform is the merchant of record for all transactions, use the Merchant docs instead.

As a platform, your implementation depends on who is the Merchant of Record:

• Sub-Merchant as MoR: The platform powers the payment experience, but each sub-merchant is the actual business the cardholder is purchasing from. You must provide account headers to both your PSP and Yeeld.

How Platform Integrations Work

As a platform, your integration manages surcharging on behalf of multiple sub-merchants. Each sub-merchant has their own Yeeld account with their own surcharge configuration. When processing a payment, you pass the sub-merchant’s Yeeld account ID in the request header so Yeeld applies the correct rules for that merchant.

Your server coordinates between your Payment Services Provider (PSP) and the Yeeld API across four steps.

1. Initialize the Payment and Calculate Surcharge

When a user selects a payment method or enters card details on your checkout page, your Client App communicates with your Server to prepare the transaction.

• Initialize Transaction: Your server requests a session or transaction object from your chosen PSP (e.g., Stripe, Adyen, or Checkout.com) to track the payment.
• Calculate Surcharge: Your server calls the Yeeld API, providing the base transaction amount and the specific payment method details (such as card brand or type). Yeeld returns the calculated surcharge amount based on the merchant’s specific rules and regional compliance.

2. Update the Transaction Total

Before the user proceeds to the final checkout step, you must synchronize your PSP’s transaction record with the calculated surcharge.

• Adjust Total Amount: Update the total amount of the transaction object within your PSP to include the Original Price + Surcharge Amount.
• Consistency: This step ensures that the amount authorized by your payment provider matches the final total displayed to the user, preventing "amount mismatch" errors during processing.

3. Display the Surcharge to the User

Transparency is critical for regulatory compliance and building user trust.

• Provide Feedback: Your server returns the Surcharge Amount and any necessary Provider Credentials (like a Client Secret or Session ID) to your Client App.
• Update the UI: Explicitly display the surcharge as a distinct line item in your checkout summary. The user must see the added fee before they click the final payment button.

4. Confirm the Payment

When the user submits the payment form, your Client App uses your PSP’s integration (SDK or API) to finalize the transaction.

• Process Total: The PSP processes the full amount, including the surcharge.
• Finalize: Once the transaction is successful, the surcharging data is logged within the Yeeld Platform for reconciliation, compliance auditing, and reporting.

Handling Changes to Payment Methods

If a user switches payment methods (e.g., from a Credit Card to a Debit Card) after the initial calculation:

• Recalculate: You must re-call the Yeeld API to determine if the surcharge amount has changed.
• Sync: Update your existing transaction object with your PSP to reflect the new total.