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:
- Register your callback URL via
POST /api/v1/redirect-urls(one-time setup, max 5 per account). - Append the URL as a query param when sharing a payment link.
- 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:
| Param | What it contains |
|---|---|
reference | The merchantReference you sent when creating the payment link (your internal ID) |
payment_id | The 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:
- Query strings are stripped —
https://yoursite.com/done?utm=xmatches a registeredhttps://yoursite.com/done. - A single trailing slash is removed —
https://yoursite.com/done/matches a registeredhttps://yoursite.com/done.
Everything else must match exactly:
- Protocol:
https://andhttp://are different. - Domain:
yoursite.comandwww.yoursite.comare 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
| Symptom | Cause |
|---|---|
| Customer sees a 404 after payment | The URL on the payment link doesn't match a registered URL byte-for-byte. |
Redirect url Limit Reached | You already have 5 URLs registered. Delete one before adding another. |
| URL not appearing in the list after POST | Confirm the response — duplicates are silently deduped, so the count may not change. |
| Redirect doesn't fire | Check that you URL-encoded the value of ?redirect_url= correctly. |