Custom Pay-in Fees

Overview

Custom pay-in fees allow merchants to add additional fee line items to purchase checkouts. These fees appear as separate line items to the customer during checkout and are added to the subtotal before payment processing.

Common use cases include:

• Regional taxes: Apply country-specific VAT or sales tax (e.g., 19% Germany VAT, 20% UK VAT)
• Service fees: Add platform or convenience fees
• Regulatory fees: Include fees that must be tracked separately from the base amount

Pay-in fees are added to the subtotal and processed as part of the total transaction. The merchant receives the full amount (subtotal + fees) in their settlement.

Configuration Methods

There are three ways to configure custom pay-in fees:

Fees passed via SDK or JWT take precedence over merchant dashboard configuration. If you pass customPayInFees via the SDK or JWT, the dashboard settings will be ignored for that transaction.

Configure Fees in Merchant Dashboard

Use the dashboard to set default fees that apply to all checkouts.

Navigate to Pay-in Fees

Log in to the Coinflow Merchant Dashboard and navigate to Payments > Pay-in Fees.

Add a Fee

Click Add Fee to create a new fee line item.

Configure Fee Details

For each fee, configure:

• Line Item Label: The text displayed to the customer (max 30 characters). Example: “Service Fee” or “VAT”
• Fee Type: Choose between a fixed dollar amount or a percentage of the subtotal
• Fee Amount: The fee value (in dollars for fixed fees, or percentage for percentage-based fees)

Preview and Save

Review the preview to see how fees will appear to customers, then click Save Changes.

The preview shows how fees will display on a $100 subtotal. Fixed fees appear as their configured amount, while percentage fees are calculated based on the subtotal.

Configure Fees via SDK

For dynamic fee application (e.g., applying different VAT rates based on customer country), pass fees directly to the Coinflow SDK.

Fee Configuration Structure

Each fee requires the following configuration:

interface PurchaseCustomPayInFee {
  lineItemLabel: string; // Display text (max 30 characters)
  fee: FixedFee | PercentageFee;
}

// Fixed fee (e.g., $2.50)
interface FixedFee {
  isFixed: true;
  percent: null;
  currency: 'USD'; // Currently only USD is supported
  cents: number;   // Amount in cents (e.g., 250 for $2.50)
}

// Percentage fee (e.g., 19%)
interface PercentageFee {
  isFixed: false;
  percent: number;  // Percentage value (e.g., 19 for 19%)
  currency: null;
  cents: null;
}

React Example

Fixed Fee

import { CoinflowPurchase } from '@coinflow/react';

function CheckoutWithServiceFee() {
  // Add a fixed $2.50 service fee
  const customPayInFees = [
    {
      lineItemLabel: 'Service Fee',
      fee: {
        isFixed: true,
        percent: null,
        currency: 'USD',
        cents: 250, // $2.50
      },
    },
  ];

  return (
    <CoinflowPurchase
      merchantId="your-merchant-id"
      subtotal={{ cents: 10000, currency: 'USD' }} // $100.00
      customPayInFees={customPayInFees}
      // ... other props
    />
  );
}

Percentage Fee (VAT)

import { CoinflowPurchase } from '@coinflow/react';

function CheckoutWithVAT({ customerCountry }) {
  // Determine VAT rate based on customer country
  const vatRate = getVatRateForCountry(customerCountry);

  const customPayInFees = vatRate > 0 ? [
    {
      lineItemLabel: `VAT (${vatRate}%)`,
      fee: {
        isFixed: false,
        percent: vatRate, // e.g., 19 for 19%
        currency: null,
        cents: null,
      },
    },
  ] : [];

  return (
    <CoinflowPurchase
      merchantId="your-merchant-id"
      subtotal={{ cents: 10000, currency: 'USD' }}
      customPayInFees={customPayInFees}
      // ... other props
    />
  );
}

function getVatRateForCountry(country: string): number {
  // Example VAT rates - these are illustrative only
  const vatRates: Record<string, number> = {
    DE: 19, // Germany
    FR: 20, // France
    UK: 20, // United Kingdom
    NL: 21, // Netherlands
  };
  return vatRates[country] || 0;
}

Multiple Fees

import { CoinflowPurchase } from '@coinflow/react';

function CheckoutWithMultipleFees() {
  // Add both a service fee and VAT
  const customPayInFees = [
    {
      lineItemLabel: 'Platform Fee',
      fee: {
        isFixed: true,
        percent: null,
        currency: 'USD',
        cents: 99, // $0.99
      },
    },
    {
      lineItemLabel: 'VAT (20%)',
      fee: {
        isFixed: false,
        percent: 20,
        currency: null,
        cents: null,
      },
    },
  ];

  return (
    <CoinflowPurchase
      merchantId="your-merchant-id"
      subtotal={{ cents: 5000, currency: 'USD' }} // $50.00
      customPayInFees={customPayInFees}
      // Customer sees:
      // Subtotal:      $50.00
      // Platform Fee:   $0.99
      // VAT (20%):     $10.00
      // Total:         $60.99
    />
  );
}

The fee values shown above (VAT rates, service fee amounts) are examples only and do not reflect actual values for your integration. Consult with your tax advisor for applicable rates and contact the Coinflow integrations team if you need assistance configuring fees for your specific use case.

Configure Fees via JWT

For server-to-server integrations, you can include customPayInFees in a JWT token. This is the most secure approach as it prevents client-side tampering with fee values.

When tokenizing your checkout parameters, include the customPayInFees array in your request:

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "subtotal": {
    "currency": "USD",
    "cents": 10000
  },
  "customPayInFees": [
    {
      "lineItemLabel": "VAT (19%)",
      "fee": {
        "isFixed": false,
        "percent": 19,
        "currency": null,
        "cents": null
      }
    },
    {
      "lineItemLabel": "Service Fee",
      "fee": {
        "isFixed": true,
        "percent": null,
        "currency": "USD",
        "cents": 250
      }
    }
  ],
  "email": "customer@example.com",
  "settlementType": "Bank"
}
'

Then pass the returned checkoutJwtToken to the Coinflow SDK or Checkout API:

SDK

<CoinflowPurchase
  merchantId="your-merchant-id"
  jwtToken={checkoutJwtToken}
  // ... other props
/>

Checkout API

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/card/your-merchant-id \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
     --data '
{
  "subtotal": {
    "currency": "USD",
    "cents": 10000
  },
  "card": { ... },
  "jwtToken": "YOUR_JWT_TOKEN"
}
'

When using the SDK without JWT tokenization, pass customPayInFees directly as a prop (see Configure Fees via SDK). For production environments with sensitive fee configurations, we recommend using JWT tokens to prevent tampering.

How Fees Are Calculated

Fees are calculated and displayed in the checkout UI as follows:

Calculation Example

For a $100.00 subtotal with:

• A fixed $2.00 service fee
• A 19% VAT

Percentage fees are calculated based on the original subtotal, not the running total. Multiple fees do not compound on each other.

Customer Experience

During checkout, customers see the fee breakdown as separate line items:

1. Subtotal - The base purchase amount
2. Custom Fee(s) - Each configured fee appears with its label and amount
3. Service Fees - Coinflow processing fees (if applicable)
4. Total - The final amount charged

This transparent breakdown helps customers understand exactly what they’re paying for.

Best Practices

Use Clear, Descriptive Labels

Choose line item labels that clearly communicate what the fee is for. Examples:

• “Service Fee” or “Platform Fee” for general fees
• “VAT (19%)” or “Sales Tax” for tax-related fees
• “Convenience Fee” for payment processing surcharges

Consider Regional Requirements

Some jurisdictions require specific fee disclosures or have regulations about surcharging. Ensure your fee configuration complies with local laws.

Test Before Going Live

Use the sandbox environment to verify fees display correctly and calculate as expected before enabling in production.