# Payment Surcharging

Note
This page details a non-essential option for merchants who have already completed April integration using the **[direct API integration](/developer-portal/direct-integration-landing)** 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](https://www.accc.gov.au/consumers/pricing/card-surcharges)
or [in New Zealand](https://comcom.govt.nz/regulated-industries/retail-payment-system/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.

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

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](https://limepay.zendesk.com/hc/en-us)
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](/openapi/april-public/payment-tokens/createpaymenttoken) or [Create pay plan](/openapi/april-public/pay-plans/createpayplan))
as part of the `surchargeRequirement` field. In this scenario, `surchargeRequirement` would be specified like


```json
{
  "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](/openapi/april-public/payment-tokens/calculatesurcharge) API, passing details of the payment, for example


```json
{
  "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](/openapi/april-public/payment-tokens/calculatesurcharge) API as per section "How to request surcharge calculation".

Step 2. Create the payment token.

For pay-in-full, call [Create Payment Token](/openapi/april-public/payment-tokens/createpaymenttoken) 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](/openapi/april-public/pay-plans/createpayplan) JSON.

Step 3. Call [Create Order](/openapi/april-public/orders/createorder) and [Pay Order](/openapi/april-public/orders/payorder) 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](/openapi/april-public/merchants/updatemerchant) 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.

Note
Configuring surcharge levels via this API does not enforce application of the surcharging.
It only controls the calculations in the [Calculate Surcharge](/openapi/april-public/payment-tokens/calculatesurcharge) API.
To ensure the surcharge is applied to the payment, you must specify `surchargeRequirement`, described above, with either the returned surcharge quote
or an explicit `SurchargeSpecified` value that you calculate independently.

To remove surcharging configuration, call the [Update Merchant](/openapi/april-public/merchants/updatemerchant) API, specifying `RemoveSurchargeConfig`.

For example, in the following specification,


```
{
  "RemoveSurchargeConfig" : {}
}
```