Redirect URLs

After a customer completes (or cancels) a payment on the Stitch Express checkout page, you usually want to send them back to your own site — to a thank-you page, an order summary, or back into your app's flow. Redirect URLs are how you do that.

The flow:

  1. Register your callback URL via POST /api/v1/redirect-urls (one-time setup, max 5 per account).
  2. Append the URL as a query param when sharing a payment link.
  3. After payment, the customer lands on your URL with ?reference=...&payment_id=... appended automatically.

Step 1: Register a URL

curl -X POST 'https://express.stitch.money/api/v1/redirect-urls' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "redirectUrl": "https://yoursite.com/payment-complete"
  }'

Response:

{
    "success": true,
    "data": {
        "redirectUrls": ["https://yoursite.com/payment-complete"]
    }
}

You only need to do this once per URL. List your registered URLs with GET /api/v1/redirect-urls, and remove one with DELETE /api/v1/redirect-urls.


Step 2: Append to a Payment Link

Given a payment link like https://express.stitch.money/DjbyqE, append the redirect URL using the redirect_url query parameter — URL-encoded:

https://express.stitch.money/DjbyqE?redirect_url=https%3A%2F%2Fyoursite.com%2Fpayment-complete

The customer pays at the original short link; on completion, they're sent to your registered URL.


Step 3: Read the Auto-Appended Params

When the customer lands on your URL, Stitch appends two query parameters:

ParamWhat it contains
referenceThe merchantReference you sent when creating the payment link (your internal ID)
payment_idThe Stitch payment ID — pass to GET /api/v1/payment/{id} for the full record

Example landing URL:

https://yoursite.com/payment-complete?reference=ORDER-12345&payment_id=abc123-def456

Use reference to look up the order in your own database; use payment_id if you need to call back into the Stitch API for status, refunds, etc.


Matching Rules — read carefully

When a customer opens a payment link with ?redirect_url=..., Stitch checks whether the supplied URL is registered before letting payment proceed. If it isn't, the customer hits a 404 — the single biggest source of redirect-related support tickets.

The match is byte-exact, with two normalizations applied to the URL on the payment link before comparison:

  1. Query strings are stripped — https://yoursite.com/done?utm=x matches a registered https://yoursite.com/done.
  2. A single trailing slash is removed — https://yoursite.com/done/ matches a registered https://yoursite.com/done.

Everything else must match exactly:

  • Protocol: https:// and http:// are different.
  • Domain: yoursite.com and www.yoursite.com are different.
  • Path: case-sensitive byte match (after trailing-slash normalization).

Register without a trailing slash. Trailing slashes are normalized off the incoming URL but not off the registered one — so https://yoursite.com/done/ in your registered list will never match anything.

If the customer hits a 404 after paying, re-fetch your registered list with GET /api/v1/redirect-urls and compare byte-for-byte against the URL on the payment link.


Limits

  • Max 5 URLs per account. Attempting to register a sixth returns Redirect url Limit Reached (400). Delete one first.
  • Duplicates are deduped. Registering a URL that already exists silently returns the existing list — the count won't increase.
  • Local development: http://localhost:... URLs are accepted for testing.

Common Errors

SymptomCause
Customer sees a 404 after paymentThe URL on the payment link doesn't match a registered URL byte-for-byte.
Redirect url Limit ReachedYou already have 5 URLs registered. Delete one before adding another.
URL not appearing in the list after POSTConfirm the response — duplicates are silently deduped, so the count may not change.
Redirect doesn't fireCheck that you URL-encoded the value of ?redirect_url= correctly.