Return URLs Unchained: Simplifying Your Crypto Payment Integrations

Hey there, code wizards and digital pioneers! 🚀 Got a minute to dive deep into some nifty updates we just pushed live? Great, because today we're unlocking some killer improvements in our crypto payment API that are sure to make your integration game smoother than ever.

The Scoop: What's New?

Ever found yourself wrestling with nested metadata just to make sure your users find their way back home after checkout? Well, fight no more! Our latest update auto-promotes top-level URLs in the POST /api/v1/payments, allowing you to simply address them as returnUrl and cancelUrl. Crucial URL handling just graduated to first class, meaning no more metadata maze for you to navigate.

Let’s Get Technical

URL Handling 101

Our latest commits focus on making those pesky URL fields a breeze. Here's the magic happening under the hood in app/api/v1/payments/route.ts:

const HTTPS_URL_RE = /^https?:\/\//i;

function isValidHttpUrl(v: unknown): v is string {
  return typeof v === "string" && HTTPS_URL_RE.test(v.trim());
}

function pickReturnUrl(body: Record<string, unknown>): string | null {
  const meta = (body.metadata && typeof body.metadata === "object" ? body.metadata : {}) as Record<string, unknown>;
  const candidates: unknown[] = [
    body.returnUrl,
    body.successUrl,
    body.merchantReturnUrl,
    meta.returnUrl,
    meta.successUrl,
    meta.merchantReturnUrl,
  ];
  for (const c of candidates) {
    if (isValidHttpUrl(c)) return c.trim();
  }
  return null;
}

function pickCancelUrl(body: Record<string, unknown>): string | null {
  const meta = (body.metadata && typeof body.metadata === "object" ? body.metadata : {}) as Record<string, unknown>;
  for (const c of [body.cancelUrl, meta.cancelUrl]) {
    if (isValidHttpUrl(c)) return c.trim();
  }
  return null;
}

This slick bit of code ensures your return URLs are always on point. It navigates through top-level and nested fields, giving preference to the top-level beauties and the explicit returnUrl over its aliases. If there's ever an invalid URL, our system will hit you with a quick 400 error, so you can course-correct in a snap.

Metadata Makeover

Previously, URLs were buried in metadata like secrets in an old pirate map. No more, me hearties! With a quick refactor, we've brought these URLs to the forefront, eliminating any chance of them being lost in translation. Here’s the transformation:

const baseMetadata: Record<string, unknown> = {
  ...(body.metadata ?? {}),
  ...(returnUrl ? { returnUrl } : {}),
  ...(cancelUrl ? { cancelUrl } : {}),
};

This update applies across the board, ensuring any payment method you choose—be it dual, crypto, or otherwise—gets the same friendly treatment. Whether you're setting up a dual-mode crypto-and-Stripe payment or sticking to the onchain life, your return and cancel URLs are ready for action.

Why Does This Matter?

For those of you who glaze over at the sight of nested JSON, this one's for you. By cutting down on unnecessary complexity, we’re saving you time and reducing the likelihood of errors in your integrations. It’s all about making your dev experience smoother than a freshly refactored codebase. Now, that's what we call developer experience (DX) luxury!

Wrapping It Up

So, what's the next step? Hit the docs, check out our openapi.yaml, and start playing with these new path-to-zen URL features. We’re all about minimizing friction and maximizing fun—and this update is a prime example of that philosophy in action.

Have a go with this fresh slab of code optimization goodness. Your users will thank you, and your future self will breathe a sigh of relief knowing you tackled this pesky little problem today.

Until next time, happy coding and may your APIs be ever RESTful! 😄

Check the Docs | Join the Community | Contribute on GitHub