Waffo Pancake Payment Service

PaymentService with waffoPaymentProvider() creates Waffo Pancake Checkout sessions through the @waffo/pancake-ts SDK and completes an existing balance topup after Waffo sends an order.completed webhook.

The service stores the Downcity payment_id in Waffo orderMerchantExternalId, so webhook sync can find the local payment record without relying on buyer-controlled fields.

Enable it

import { Federation } from "@downcity/city";
import {
  BalanceService,
  PaymentService,
  waffoPaymentProvider,
} from "@downcity/services";

const base = new Federation({ db });
const balance = new BalanceService();

base.use(balance);
base.use(new PaymentService({
  // PaymentService takes `readTopup` and `finishTopup` directly.
  // There is no balance bridge object anymore.
  readTopup: async (topup_id) => await balance.readTopup(topup_id),
  finishTopup: async (topup_id, extra) => await balance.finishTopup(topup_id, extra),
  providers: [
      waffoPaymentProvider({
        merchant_id: process.env.WAFFO_MERCHANT_ID,
        private_key: process.env.WAFFO_PRIVATE_KEY,
        product_id: process.env.WAFFO_PRODUCT_ID,
        webhook_public_key: process.env.WAFFO_WEBHOOK_PUBLIC_KEY,
      }),
  ],
}));

Required env

• WAFFO_MERCHANT_ID: Waffo Merchant ID, for example MER_6gyg0Q5asJBoY5GSNmZt7P
• WAFFO_PRIVATE_KEY: Waffo API private key used by @waffo/pancake-ts
• WAFFO_PRODUCT_ID: Waffo product used for Checkout
• WAFFO_WEBHOOK_PUBLIC_KEY: optional webhook public key; the SDK can also use its built-in Waffo keys
• WAFFO_ENVIRONMENT: optional test or prod; defaults to test
• DOWNCITY_CITY_BASE_URL: optional public City base URL used to derive built-in result pages
• WAFFO_CURRENCY: optional display currency for payment method discovery
• WAFFO_API_BASE_URL: optional API base URL override for tests

The Waffo success redirect URL is generated automatically from DOWNCITY_CITY_BASE_URL. If it is not configured, the service falls back to the current request origin for local development.

Frontend flow

Create a trusted topup first through balance, then create a Waffo checkout for it:

const checkout = await user.service("payment").action("checkout/create").invoke({
  method_id: "waffo",
  topup_id: "topup_demo",
});

location.href = checkout.checkout_url;

PaymentService() exposes Waffo through:

const methods = await guest.service("payment").get("methods");

The Waffo method is enabled only when WAFFO_MERCHANT_ID, WAFFO_PRIVATE_KEY, and WAFFO_PRODUCT_ID are configured.

Webhook sync

Configure Waffo to send webhook events to:

POST /v1/payment/webhook

The service verifies x-waffo-signature with the Waffo SDK and applies order.completed once per delivery id.

Routes

• GET /v1/payment/methods
• POST /v1/payment/checkout/create
• GET /v1/payment/payments/me
• GET /v1/payment/payments
• GET /v1/payment/events
• POST /v1/payment/webhook
• GET /v1/payment/redirect/success
• GET /v1/payment/redirect/cancel