1. Overview
2. Money movement

Facilitator fees can be applied to any type of transfer, and the amount specified will be deducted from the transfer so that the destination receives the transfer amount net of fees. The fee amount is credited to your wallet once the transfer is completed.

Moov charges a fee to your platform to process most payments. Depending on the transfer type, the Moov fee may be incurred at the time of the payment.

Facilitator fee types

Moov currently supports two types of facilitator fees: total and markup.

• total: Utilizing the total facilitator fee type allows you to charge a flat fee to the merchant regardless of what interchange and other costs amount to. The total fee type would be appropriate for billing something like 4.00% per transfer.

• markup: The markup facilitator fee type is what you want to use if you want to bill an amount on top of the Moov fee. Note that the Moov fee includes interchange and other pass-through costs which can vary from transfer to transfer. The markup fee type would be appropriate for billing something similar to Interchange + 1.90% & $0.10. The markup fee is debited from your platform account wallet, not the merchant.

In place of total and markup, you have the option to use totalDecimal and markupDecimal, which support cents in fractions, up to nine decimal places. Only one of total or totalDecimal, or markup or markupDecimal can be used.

View the facilitatorFee object in the API for more details.

Charging fees on transfers

To collect a fee, you can utilize the facilitatorFee field in the create a transfer POST request. When specifying the fee amount, there are a few different options:

Implementing fees via the API

Using the facilitatorFee field in the transfer request, you can set a markup or total fee. See examples of each kind of fee below:

Example of markup fee

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

curl -X POST "https://api.moov.io/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "currency": "USD",
      "value": 10000
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID"
    },
    "facilitatorFee": {
      "markup": 100
    }
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

const moov = new Moov(credentialsObject);

const transferPayload = {
  amount: {
    value: 100,
    currency: "USD"
  },
  destination: {
    paymentMethodID: "destination-payment-method-id"
  },
  source: {
    paymentMethodID: "source-payment-method-id"
  },
  facilitatorFee: {
    markup: 100
  },
  idempotencyKey: "UUID"
}

const transfer = await moov.transfers.create(transferPayload);

Example of total fee

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

curl -X POST "https://api.moov.io/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "currency": "USD",
      "value": 10000
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID"
    },
    "facilitatorFee": {
      "total": 400
    }
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

const moov = new Moov(credentialsObject);

const transferPayload = {
  amount: {
    value: 100,
    currency: "USD"
  },
  destination: {
    paymentMethodID: "destination-payment-method-id"
  },
  source: {
    paymentMethodID: "source-payment-method-id"
  },
  facilitatorFee: {
    total: 400
  },
  idempotencyKey: "UUID"
}

const transfer = await moov.transfers.create(transferPayload);

Retrieve fees charged on a transfer

Once a transfer is successfully created, Moov automatically creates subsequent transactions representing the associated fees on that transfer. These fees will not be charged until the transfer successfully reaches the destination.

Moov fee

Moov charges a fee (moovFee) to your platform account for card transfers, and rounds to the nearest cent. The moovFeeDecimal provides the details of the precise fee charged, up to nine decimals.

Transfers with the card-payment payment method as the source incur a Moov fee that includes interchange and other passthrough costs that are finalized at the time the transfer is completed. See the passthrough network fees guide for detailed information on interchange and card scheme fees.

You can find Moov fee details in the GET transfers API response.

Fee guidelines

Fee amounts must not exceed the maximum amounts described below.

For facilitator fee with type total:

• The fee amount must be less than the transfer amount

For facilitator fee with type markup, the maximums depend on what kind of transfer you are making:

• card-acquiring: The customer provided markup amount + Moov fee charges + estimated maximum interchange (4% of transfer amount) must be less than the transfer amount
• rtp or push-to-card: The customer provided markup amount + the Moov fee amount must be less than the transfer amount

Additionally, if you have not specified a facilitator fee and Moov charges a fee at the time of transfer¹, Moov will debit your wallet the amount of the Moov fee. If your wallet does not have enough funds to cover the fees, the debits will result in a negative wallet balance.

Wallet transactions

Your account receives the full facilitatorFee and is debited the moovFee. You’ll see each debit and credit in your Moov wallet.