Payment Surcharging

Surcharging is the practice of adding an extra fee or charge to the regular price of a product or service. This additional fee is often applied to cover specific costs associated with payment processing or as a way to increase revenue.

Payment surcharging allows a merchant to apply a surcharge in order to a payment pass on April's fees to the end customer. The amount of the surcharge is configured for the merchant (or marketplace) according to rules based on attributes of the payment method. These rules can be coarse-grained, such as applying to all cards, or fine-grained rules that allow customised surcharging strategies depending on criteria such as card funding type (credit / debit), card brand (eg Visa), country of card issue, etc. The rules can specify that the surcharge can cover exactly the platform fees that April charges. Alternatively, the rules can specify explicit fixed and variable (a fraction of the payment total) amounts.

In the case of split payment authorisation and capture, the surcharge level is calculated based at the time of payment authorisation based on the amount specified at that stage.

Integrating Payment Surcharging via the April API

There are two approaches.

Front-end integration

This approach is where the surcharge is introduced as part of the customer user interface flow.

In the less common event that you are developing your own checkout user interface, then you will need to follow the same steps that the April checkout does in order to integrate with April's back-end APIs. See section "How to implement a custom front-end integration", below.

Back-end integration

In this approach, your back-end application is directly integrating with April's back-end.

There are two options for handling the surcharge amount.

Option 1. Call the April surcharge calculation API as per section "How to request surcharge calculation", below.

Option 2. Specify the surcharge to April explicitly. In this approach, you take responsibility for calculating and imposing the specified surcharge, which is passed to the payment creation API (Create Payment Token or Create pay plan) as part of the surchargeRequirement field. In this scenario, surchargeRequirement would be specified like

{
  "SurchargeSpecified" : {
    "surchargeAmount" : 250
  }
}

The surchargeAmount value is in the same currency as the payment, and in the same currency units, eg cents for AUD.

How to request surcharge calculation

Call the Calculate Surcharge API, passing details of the payment, for example

{
  "PaymentSurcharge" : {
    "payment" : {
      "form" : {
        "PayInFull": { }
      },
      "customerType" : "Organisation",
      "amount" : {
        "amount" : 100000,
        "currency" : "AUD"
      },
      "method" : {
        "Card" : {
          "cardNumber" : "4242424242424242"
        }
      }
    }
  }
}

Note: the amount is in cents for AUD. As you are passing in a card PAN, your application must be PCI-compliant to call this API.

The response to this message is a "surcharge quote". You need to save this quote in order to pass it to the next step.

How to implement a custom front-end integration

Step 1. Call the Calculate Surcharge API as per section "How to request surcharge calculation".

Step 2. Create the payment token.

For pay-in-full, call Create Payment Token and pass the surcharge quote in the surchargeRequirement field, for example

{
  "CreateManualCardToken": {
    "amount": {
      "minorCurrencyUnits": 100000,
      "currency": "AUD"
    },
    "card": {
      "number": "4242424242424242",
      "cvc": "123",
      "expiryDate": {
        "expiryMonth": "06",
        "expiryYear": "2026"
      }
    },
    "surchargeRequirement": {
      "surchargeQuote": {
        "unsurchargedAmount": 100000,
        "surchargeAmount": 250,
        "totalAmount": 100250,
        "paymentMethod": { ... },
        "quoteVerificationToken": "xxxxxx"
      }
    }
  }
}

Note: the entire surchargeQuote JSON object is copied from the reply to Step 1, above, and inserted into this JSON.

For pay plans (BNPL), there is a similar surchargeRequirement in the Create pay plan JSON.

Step 3. Call Create Order and Pay Order as usual. The surcharge quote has been saved as part of the payment token, and will be automatically applied to the payment.

How to configure surcharging

For marketplaces, it is possible to directly configure the surcharging levels for one of your merchants. Call the Update Merchant API, specifying SetSurchargeConfig, which specifies surcharging by card type.

For example, in the following specification,

{
  "SetSurchargeConfig" : {
    "surchargeRules" : [
      {
        "surchargeFor" : {
          "SurchargeForCardBrands" : {
            "cardBrand" : [
              "Visa",
              "MasterCard"
            ]
          }
        },
        "surchargeBy" : {
          "fixedAmount" : 30,
          "variablePercentage" : 2.5
        }
      },
      {
        "surchargeFor" : {
          "SurchargeForCardBrands" : {
            "cardBrand" : [
              "American Express"
            ]
          }
        },
        "surchargeBy" : {
          "fixedAmount" : 40,
          "variablePercentage" : 4
        }
      }
    ],
    "fallback" : {
      "fixedAmount" : 20,
      "variablePercentage" : 2.5
    }
  }
}

Visa and MasterCard payments incur a 2.5% + $0.30 surcharge, AMEX payments incur a 4.0% + $0.40 surcharge, and any other payments incur the fallback 2.5% + $0.20 surcharge.

To remove surcharging configuration, call the Update Merchant API, specifying RemoveSurchargeConfig.

For example, in the following specification,

{
  "RemoveSurchargeConfig" : {}
}