Merchant

Use this guide if you process payments directly as the merchant of record. If you’re routing payments on behalf of other businesses, see Platforms and Marketplaces instead.

Overview

To implement surcharging, your integration must manage the synchronization between your Payment Service Provider (PSP) and the Yeeld API across four primary phases.

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.