Skip to main content

Onboarding API: fee profiles

How to build the discounting (fee profile) object for each store, with field rules and an example.

A fee profile is the discounting object on each store. It sets the merchant’s fees and the rate charged per card type and card state.

Fields

Field

Type

Description

name

string

Profile name. Required, and can’t be empty.

cycle

enum

Billing cycle, for example DAILY

rateType

enum

Pricing model, for example FLAT

chargebackFee

number

Fee per chargeback, within the country’s tier

achReturnFee

number

Fee per ACH return, within the country’s tier, or 0 where ACH is disabled

feeProfiles

array

One entry per card type and card state

feeProfiles[].cardType

enum

For example VISA or MASTERCARD

feeProfiles[].cardState

enum

For example CARD_PRESENT

feeProfiles[].rate

number

Rate on each transaction, as a decimal

feeProfiles[].crossborderRate

number

Extra rate on cross-border transactions, as a decimal

feeProfiles[].transactionFee

number

Fixed amount per transaction, for example 0.1

cardTypesToEnable

object

Card types to switch on; send {} for the defaults

amexType

enum

Amex program, for example OPT_BLUE

midNumber

string

Optional Amex merchant number

The full value lists for each enum are in the API spec at /api-docs/ on the onboarding host.

Rules

  • Rates are decimal fractions with up to 4 decimal places: 0.0265 is 2.65%, and 0.05 is 5%. Sending 2.65 means 265%.

  • Fees follow the country’s tier. Chargeback and ACH return fees must be inside the tier’s range, and ACH fees must be 0 where ACH is disabled (see Onboarding API: supported countries and regions).

Example

A Canadian card-present profile (tier 2: fees 10 to 100):

{
"name": "Standard CA card present",
"cycle": "DAILY",
"rateType": "FLAT",
"chargebackFee": 35,
"achReturnFee": 35,
"feeProfiles": [
{ "cardType": "VISA", "cardState": "CARD_PRESENT", "rate": 0.0265, "crossborderRate": 0.01, "transactionFee": 0.1 },
{ "cardType": "MASTERCARD", "cardState": "CARD_PRESENT", "rate": 0.0265, "crossborderRate": 0.01, "transactionFee": 0.1 }
],
"cardTypesToEnable": {},
"amexType": "OPT_BLUE"
}
Did this answer your question?