Getting Started

Welcome to Kwenta! A payment platform that allows your customers to pay a single order with friends (many_payers) or with multiple cards (single_payer).

This guide will walk you through the basics of integrating with our service, please go to the Integration section for more advanced topics.

If you'd like to dive deeper into the examples, you can find the source code on the kwentapay/express-example GitHub repository.

For now, backend-side examples are written with JavaScript and Express but our API can be consumed from any programming language. It's even possible to generate client libraries.

In-case you have any questions, please don't hesitate to contact us.

Prerequisites

Create a Kwenta account

Before you can start using Kwenta, you'll need to create a test account on the kwenta.st Dashboard.

Please read the Sign up guide for more information.

Get an API key

Once you've created an account, you'll need to generate an API key.

You can do so by visiting the API Keys page of the Kwenta Dashboard settings page.

More details can be found on the Authentication guide.

Connect your backend

Depending on your backend language, you'll need to install one of our client libraries or call the API directly.

Create a new order

To create a new order, you'll need to call the POST /orders endpoint from your backend with:

  • The type of order to create. It must be one of:
    • many_payers aka. Pay with friends
    • single_payer aka. Pay with multiple cards
  • The currency to be used, expressed as an ISO 4217 code in uppercase letters.
  • The total amount to pay expressed in the smallest unit of the currency (i.e. in cents for EUR and USD).
  • An optional redirectUrl parameter that your customer will be redirected to after they complete their payment or whenever they click on the Back to {Name} button.
  • An optional sellerOrderId parameter that you can use to associate the Kwenta order with your own.

This will create a new order entity on Kwenta and return an object which includes:

  • An id that you can use to track the order.
  • A url property that you can use to redirect your customer to Kwenta.

Copy
Copied
// backend/create-order.js

const express = require("express");
const { Kwenta } = require("@kwentapay/api-client");

const app = express();
app.use(express.json());

const kwenta = new Kwenta({ apiKey: process.env.KWENTA_API_KEY });

app.post("/api/create-order", async (req, res) => {
  // In a real app you would use the id of your order instead of a random UUID.
  const orderId = randomUUID();

  // Create a new order with the correct amount and currency.
  const kwentaOrder = await kwenta.createOrder({
    // In a real app you would forward the order type from the frontend
    // depending on the Kwenta button the customer clicked on.
    type: req.body.kwentaOrderType,

    // In a real app you would use the amount and currency of your order
    // instead of a fixed value.
    amount: 12399,
    currency: "EUR",

    // An optional parameter that you can use to redirect the customer
    // to your website after they complete their payment.
    redirectUrl: `https://example.com/order/${orderId}`,

    // An optional parameter that you can use to associate the Kwenta order
    // with your own.
    sellerOrderId: orderId,
  });

  // In a real app you would store the Kwenta order id in your database
  // so that you can retrieve it later.
  console.debug(`${orderId} -> ${kwentaOrder.id}`, kwentaOrder);

  // Return the order URL to the frontend so that the customer can be redirected
  // to Kwenta in order to pay.
  res.json({ url: kwentaOrder.url });
});

More information about the createOrder endpoint can be found on the Create a new order guide and its API reference page.

Redirect your customer to Kwenta

Once the order has been created, you'll need to redirect your customer to the url that was returned from the createOrder endpoint.
Copy
Copied
// frontend/checkout.js

// Call your backend to create the order.
// The backend should return the Kwenta order URL which
// is unique to each Kwenta order.
const kwentaOrderUrl = await createOrderFromSellerBackend();

// Set the window location to the Kwenta order URL.
window.location.href = kwentaOrderUrl;
With some frameworks (e.g. Next, Remix), you might need to use their own router instead of setting window.location.href.

See the Redirect the customer to Kwenta guide for more information.

Track the order status

In-order to trigger the fulfillment of an order within your system, you'll have to listen to the order.paid event.
Copy
Copied
// backend/kwenta-webhook-listener.js

const express = require("express");
const { Kwenta } = require("@kwentapay/api-client");

const app = express();
app.use(express.json());

const kwenta = new Kwenta({ apiKey: process.env.KWENTA_API_KEY });

// This endpoint is called by kwenta when the user has completed the checkout.
app.post("/api/kwenta-webhooks", async (req, res) => {
  console.debug(`Webhook received`, req.body);

  // Only act on a specific event type.
  if (req.body.event !== "order.paid") {
    // In a real app you would probably want to:
    //   - check that the event is in-sync with your database by calling the
    //     `getOrderById` endpoint.
    //   - store the order in a database.
    //   - trigger internal fulfillment processes.
    console.info(`Order ${req.body.orderId} is now paid!`);
  }

  // Return a 200 OK response to Kwenta
  res.sendStatus(200);
});

If information about the payment of an order changes, Kwenta will send a webhook to the endpoints you've registered.

The body of the webhook will contain the id of the order that was updated.

To add a new webhook endpoint URL, go to the Webhooks page of the Kwenta dashboard and enter the public URL that must be called.

warning

Keep in mind that the webhooks are sent asynchronously and that you should not rely on them to update the order status in real-time.

Whenever you need to get the latest information about an order, you should call the getOrderById endpoint from your backend.

More information about webhooks can be found on the Webhooks guide.

Handle customer returns to your website

When creating an order with its redirectUrl property filled, Kwenta will redirect the customer to that URL after they complete their payment or Whenever they click on the Back to {Name} button.

Depending on your website, you'd want this page to handle the following scenarios:

  • The customer has completed their payment.
  • The customer has cancelled their payment.
  • The customer has pressed the "Back to {Name}" button.
Copy
Copied
// frontend/order.$id.js

// Call your own backend to get an up-to-date order status in a secure way.
const order = await getOrderFromBackend();

// Update the UI depending on the order status.
document.getElementById("status").innerText = order.status;

You can find additional information on the Handle customer returns to your website guide.

Next steps

Now that you've learned the basics of using Kwenta, you can learn more about how to Integrate with Kwenta or read the API Reference.