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

Configuration Methods

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

Configure Fees in Merchant Dashboard

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

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:

1
interface PurchaseCustomPayInFee {
2
  lineItemLabel: string; // Display text (max 30 characters)
3
  fee: FixedFee | PercentageFee;
4
}
5
6
// Fixed fee (e.g., $2.50)
7
interface FixedFee {
8
  isFixed: true;
9
  percent: null;
10
  currency: 'USD'; // Currently only USD is supported
11
  cents: number;   // Amount in cents (e.g., 250 for $2.50)
12
}
13
14
// Percentage fee (e.g., 19%)
15
interface PercentageFee {
16
  isFixed: false;
17
  percent: number;  // Percentage value (e.g., 19 for 19%)
18
  currency: null;
19
  cents: null;
20
}

React Example

1
import { CoinflowPurchase } from '@coinflow/react';
2
3
function CheckoutWithServiceFee() {
4
  // Add a fixed $2.50 service fee
5
  const customPayInFees = [
6
    {
7
      lineItemLabel: 'Service Fee',
8
      fee: {
9
        isFixed: true,
10
        percent: null,
11
        currency: 'USD',
12
        cents: 250, // $2.50
13
      },
14
    },
15
  ];
16
17
  return (
18
    <CoinflowPurchase
19
      merchantId="your-merchant-id"
20
      subtotal={{ cents: 10000, currency: 'USD' }} // $100.00
21
      customPayInFees={customPayInFees}
22
      // ... other props
23
    />
24
  );
25
}

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:

1
curl --request POST \
2
     --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
3
     --header 'Authorization: YOUR_API_KEY' \
4
     --header 'accept: application/json' \
5
     --header 'content-type: application/json' \
6
     --data '
7
{
8
  "subtotal": {
9
    "currency": "USD",
10
    "cents": 10000
11
  },
12
  "customPayInFees": [
13
    {
14
      "lineItemLabel": "VAT (19%)",
15
      "fee": {
16
        "isFixed": false,
17
        "percent": 19,
18
        "currency": null,
19
        "cents": null
20
      }
21
    },
22
    {
23
      "lineItemLabel": "Service Fee",
24
      "fee": {
25
        "isFixed": true,
26
        "percent": null,
27
        "currency": "USD",
28
        "cents": 250
29
      }
30
    }
31
  ],
32
  "email": "customer@example.com",
33
  "blockchain": "solana",
34
  "settlementType": "USDC"
35
}
36
'

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

1
<CoinflowPurchase
2
  merchantId="your-merchant-id"
3
  jwtToken={checkoutJwtToken}
4
  // ... other props
5
/>

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

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