Payment Surcharging

Note

This page details a non-essential option for merchants who have already completed April integration using the direct API integration method.

If you are using an e-commerce platform such as Magento, Woocommerce or Salesforce, this section is not relevant to your integration of April. However, you can enable surcharging by contacting April Customer Success.

Important

Charging customers excessive processing fees is prohibited by law, and it is your responsibility to comply with the regulations. Learn more about surcharging in Australia or in New Zealand.

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.

info

If you are using April's checkout, then this flow is available to you without any additional integration development effort. April's Customer Success team will configure your surcharge fee structure at time of onboarding, and the rest happens automatically under control of the April checkout UI.

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

info

This approach involves sending RAW card details to an April API endpoint to tokenize within our systems in a PCI-compliant manner. This API is only available to integrators who are themselves PCI-certified and have a pre-arranged agreement with April Solutions. Please contact support if you wish to discuss the process.

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

Copy
Copied
{
  "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

Copy
Copied
{
  "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

Copy
Copied
{
  "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,

Copy
Copied
{
  "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,

Copy
Copied
{
  "RemoveSurchargeConfig" : {}
}
Copyright © April Solutions 2023. All right reserved.