Introducing Dynamic Surcharging for API Providers

We are excited to introduce a new feature that enables API providers to implement dynamic surcharging through Dhali. This allows for greater flexibility in pricing, offering a way to dynamically adjust costs based on various factors, in addition to the existing per-request and per-second pricing models. Here's how this works and how you can take advantage of it.

How Dynamic Surcharging Works

At its core, dynamic surcharging lets API providers set an additional charge—over and above the base API fees—that can be applied conditionally. This is particularly useful for APIs that may incur higher costs based on factors like load, specific network traffic, or other dynamic variables.

To enable surcharging on your API, simply adjust the maximum surcharge value when configuring your API within Dhali.

Once set, the process is handled as follows:

1. Request Handling with Surcharge Header
   When a user accesses your surcharge-enabled API, Dhali automatically forwards the request with an additional header:
   X-Payment-Claim-Surcharge-Currency.

This header contains important information, including the currency code, network type, maximum surcharge allowed, and other details. The information is encoded in base64 format, but the structure when decoded looks like this:

{
  "schema": "0.0.1",
  "networkType": "XRPL",
  "networkID": 1,
  "code": "XRP",
  "scale": 6,
  "maxAmount": 1000000
}

1. API Provider Response with Surcharge
   Upon receiving the request, your API can calculate and respond with the surcharge amount it wishes to apply. This response is sent via the X-Payment-Claim-Surcharge header, also base64-encoded. When decoded, it looks like this:

{
  "schema": "0.0.1",
  "amount": 50000
}

In this example, the surcharge of 50,000 drops (the scale of 6 implies each currency unit is a factor of 10e6 smaller than the currency code) is added on top of the base price for that API call.

Practical Example of Encoding and Decoding

Let’s look at how to encode and decode the surcharge headers using JavaScript. Here’s an example of how to encode the X-Payment-Claim-Surcharge-Currency:

const data = { schema: "0.0.1", code: "XRP", maxAmount: 1000000 };
const jsonString = JSON.stringify(data);
const base64EncodedString = Buffer.from(jsonString).toString('base64');
console.log(base64EncodedString);  // Encoded string

And here’s how you would decode it:

const decodedBytes = Buffer.from(base64EncodedString, 'base64');
const decodedJsonString = decodedBytes.toString('utf-8');
const originalData = JSON.parse(decodedJsonString);
console.log(originalData);  // Decoded JSON object

These simple steps help handle the surcharge data as it passes between Dhali and your API.

Benefits of Dynamic Surcharging

With dynamic surcharging, you can adjust the price of your API based on real-time factors, making your pricing model more adaptable. This gives you greater control over API revenues, allowing you to capture additional value from high-traffic or high-cost periods. It also allows you to specify premium components of your API, where surcharges may apply.

Developed in Partnership with XRPLF

This feature was built in collaboration with Wietse Wind and the XRPL Foundation, helping them support the needs of their XRPL Cluster integration.

Get Started with Dynamic Surcharging

To activate dynamic surcharging, link a wallet with Dhali and enable the surcharge option for your API by specifying the maximum surcharge amount. From there, your API will be able to receive surcharge headers, calculate appropriate amounts, and respond with the necessary pricing information. The setup process is straightforward, but if you need any assistance, our documentation and support team are always here to help.

Dynamic surcharging adds a powerful new tool to your API pricing strategy—try it out today!