Fees

Moov makes it easy for you to monetize your payment flows by collecting a facilitator fee when creating a transfer. Use this guide to learn how to set up facilitator fees, and understand the fees Moov charges you.

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

In the API, the fee amount is calculated in cents. For example, a markup fee amount of 100 is equivalent to $1.

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:

Markup fee flow diagram

Use the markup option to achieve Interchange+ pricing.

You can either pass on your exact cost, setting markup to 0, or indicate an additional amount you want to collect on top of your cost. Keep in mind that anything above your cost must be calculated in your system and the markup must be sent to Moov as a dollar amount.

For example, let’s assume the following:

  • $100.00 transfer
  • Interchange = $2.00
  • Facilitator pricing = Interchange + 0.90% & $0.10
  • Merchant pricing = Interchange + 1.90% & $0.10

In this scenario, the total Moov fee is $3.00. The goal is to net a total of interchange ($2.00) plus 1.90% ($1.90) and $0.10 ($0.10) = $4.00 from the transfer amount. A markup of $1.00 is required.

markup = merchant pricing - facilitator pricing - interchange

Specified fee flow diagram

Use total to charge a flat fee, regardless of the Moov fee.

If you want to charge 4%, calculate the total to 0.04 * transferAmount to know what amount to send Moov, in this case $4.00.

If the transfer amount is $100 and the total facilitator fee is $4, the net amount received by the destination is $96, and you will receive $4 minus the Moov fee in your wallet.

If the total fee is less than the Moov fee, your wallet will be debited instead of credited.

Specified fee flow diagram

If the facilitatorFee field is left blank, Moov will apply a default fee of $0 and the destination will receive the gross amount of the transfer. Your platform wallet will be debited any Moov fees that apply.

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
mc := moov.NewClient()

mc.CreateTransfer(ctx, moov.CreateTransfer{
  Amount: moov.Amount{
    Currency: "usd",
    Value:    100, // $1.00
  }
  Source: moov.CreateTransfer_Source{
    PaymentMethodID: source, 
  },
  Destination: moov.CreateTransfer_Destination{
    PaymentMethodID: dest,
  },
  FacilitatorFee: moov.CreateTransfer_FacilitatorFee{
    markup: 100
  },
  IdempotencyKey: "UUID",
)
 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
mc := moov.NewClient()

mc.CreateTransfer(ctx, moov.CreateTransfer{
  Amount: moov.Amount{
    Currency: "usd",
    Value:    100, // $1.00
  }
  Source: moov.CreateTransfer_Source{
    PaymentMethodID: source, 
  },
  Destination: moov.CreateTransfer_Destination{
    PaymentMethodID: dest,
  },
  FacilitatorFee: moov.CreateTransfer_FacilitatorFee{
    total: 400
  },
  IdempotencyKey: "UUID",
)
 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 transfer1, 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.


  1. Moov currently only applies fees on card payments. Other payment methods are billed separately. ↩︎

Summary Beta