Stitch Express API — Quick Start Guide
Overview
The Stitch Express API lets you programmatically create payment links, manage subscriptions, process refunds, and more. All amounts are in South African cents (e.g. 5000 = R50.00).
Base URL: https://express.stitch.money
Step 1: Get Your Credentials
You'll need a client ID and client secret from the Stitch Express dashboard. Test credentials are prefixed with test-.
Step 2: Authenticate
Call POST /api/v1/token to get a Bearer token. Tokens are valid for 15 minutes.
curl -X POST 'https://express.stitch.money/api/v1/token' \
-H 'Content-Type: application/json' \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"scope": "client_paymentrequest"
}'
Response:
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs..."
}
}
Use this token in the Authorization header for all subsequent calls:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Scopes
The scope field determines which endpoints your token can access:
| Scope | What it unlocks |
|---|---|
client_paymentrequest (default) | Payment links, payments, refunds, fees, withdrawals, account, webhooks |
client_recurringpaymentconsentrequest | Card consents and subscriptions (not enabled by default) |
client_terminal_session | Terminals, stores and terminal sessions. Also accepted on payment, refund and webhook endpoints, so in-person integrations need one token |
client_refund | Accepted on refund endpoints; not required, as client_paymentrequest and client_terminal_session tokens can refund too |
Only card consent, subscription, terminal, store and terminal-session endpoints enforce a specific scope. Calling one of those with a different scope returns 403 Forbidden with code: invalid_scope.
Step 3: Create a Payment Link
Only amount, payerName, and merchantReference are required.
curl -X POST 'https://express.stitch.money/api/v1/payment-links' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"amount": 5000,
"payerName": "John Doe",
"merchantReference": "order-abc-123"
}'
Response:
{
"success": true,
"data": {
"payment": {
"id": "abc123-def456",
"amount": 5000,
"status": "PENDING",
"payerName": "John Doe",
"link": "https://express.stitch.money/DjbyqE",
"expireAt": "2026-05-22T00:00:00.000Z"
}
}
}
Send the link URL to your customer. They'll see a checkout page to complete payment.
Optional: Redirect After Payment
Register a redirect URL first:
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"
}'
Then append it to the payment link:
https://express.stitch.money/DjbyqE?redirect_url=https%3A%2F%2Fyoursite.com%2Fpayment-complete
Step 4: Get Notified via Webhooks
Webhooks are the recommended way to learn that a payment completed — see the Webhooks guide for signature verification and retries. Register a webhook URL to receive payment events:
curl -X POST 'https://express.stitch.money/api/v1/webhook' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://yoursite.com/webhooks/stitch"
}'
Response includes a signing secret — save this securely for verifying webhook requests.
Event Types
| Event | When it fires |
|---|---|
payment.paid | Customer has completed the payment |
Webhook Payload
{
"amount": 5000,
"id": "payment-uuid",
"status": "PAID",
"type": "LINK",
"linkId": "link-uuid",
"consentId": null,
"subscriptionId": null,
"terminalSessionId": null
}
The type field tells you how the payment was created (LINK, CONSENT, SUBSCRIPTION, or TERMINAL). Only successful payments are delivered — expired or cancelled links and failed terminal sessions do not produce a webhook.
Verifying Webhooks
Webhooks are delivered via Svix. Each request includes three headers for verification:
svix-id— Unique message IDsvix-timestamp— Unix timestampsvix-signature— HMAC signature
Use the signing secret from the webhook creation response to verify these headers. See the Svix verification docs for implementation details in your language.
Step 5: Look Up a Payment
Use these endpoints to fetch full payment details after a webhook or for reconciliation. Don't poll them as your primary signal that a payment completed — use webhooks for that. A payment record only exists once paid, so non-success outcomes live on the originating resource: GET /api/v1/payment-links/{id} for an expired or cancelled link, GET /api/v1/terminal-sessions/{id} for a failed terminal session.
Fetch a specific payment:
curl 'https://express.stitch.money/api/v1/payment/PAYMENT_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'
Or query recent payments:
curl 'https://express.stitch.money/api/v1/payment?startTime=2026-07-01T00:00:00%2B02:00&limit=100' \
-H 'Authorization: Bearer YOUR_TOKEN'
Timezone offsets are supported in startTime/endTime (URL-encode + as %2B). Without a window, the last 30 days of payments are returned (from midnight, South African time), capped at limit (default 100, max 500, most recent first).
GET /api/v1/payment accepts 120 requests per minute per client ID. Each endpoint and HTTP method has its own limit, so polling this endpoint does not use up the limit on POST /api/v1/payment-links. A request over the limit gets a 429 response with a Retry-After header that gives the seconds until you can retry. The API reference lists every endpoint's limit.
Recurring Payments (Card Consents & Subscriptions)
The client_recurringpaymentconsentrequest scope is not enabled by default. You need it for saving cards, subscription billing, and DebiCheck mandates. Once it is enabled on your client, request a token with scope: "client_recurringpaymentconsentrequest".
Common Errors
| Error | Cause | Fix |
|---|---|---|
invalid_client | Wrong or regenerated secret | Your secret was regenerated when someone viewed it in the dashboard. Recopy it from Settings. |
Invalid client secret | Secret doesn't match | Same as above — viewing the secret regenerates it. Only view when ready to copy. |
401 Unauthorised | Missing or expired token | Request a new token via POST /api/v1/token (tokens last 15 minutes) |
403 Forbidden | Wrong scope for the endpoint | Check the scope table above. Card consent/subscription endpoints need client_recurringpaymentconsentrequest; terminal, store and terminal-session endpoints need client_terminal_session. |
400 with field errors | Invalid request body | Check the field-level error messages in the response |
| Amount validation error | Amount below minimum | Amounts are in cents — minimum is 100 (R1.00) |
About client secrets
Every time you view your client secret in the dashboard, it is regenerated. The previous secret immediately stops working. This is the #1 cause of invalid_client errors. Only view the secret when you are ready to copy it directly into your integration. If multiple developers are working on the same project, coordinate so that one person's dashboard visit doesn't break another's integration.
Amount Reference
All monetary values in the API are in South African cents:
| Rands | Cents (API value) |
|---|---|
| R1.00 | 100 |
| R10.00 | 1000 |
| R50.00 | 5000 |
| R100.00 | 10000 |
| R1,000.00 | 100000 |
Next Steps
- Refunds:
POST /api/v1/payment/{paymentId}/refund - Subscriptions:
POST /api/v1/subscriptions(requiresclient_recurringpaymentconsentrequestscope) - Card Consents:
POST /api/v1/card-consents(requiresclient_recurringpaymentconsentrequestscope) - Account Balance:
GET /api/v1/account/balance - Withdraw Funds:
POST /api/v1/withdrawal
See the full API reference at express.stitch.money/api-docs.