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:

ScopeWhat it unlocks
client_paymentrequest (default)Payment links, payments, refunds, fees, withdrawals, account, webhooks
client_recurringpaymentconsentrequestCard consents and subscriptions (not enabled by default)
client_terminal_sessionTerminals, stores and terminal sessions. Also accepted on payment, refund and webhook endpoints, so in-person integrations need one token
client_refundAccepted 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

EventWhen it fires
payment.paidCustomer 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 ID
  • svix-timestamp — Unix timestamp
  • svix-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

ErrorCauseFix
invalid_clientWrong or regenerated secretYour secret was regenerated when someone viewed it in the dashboard. Recopy it from Settings.
Invalid client secretSecret doesn't matchSame as above — viewing the secret regenerates it. Only view when ready to copy.
401 UnauthorisedMissing or expired tokenRequest a new token via POST /api/v1/token (tokens last 15 minutes)
403 ForbiddenWrong scope for the endpointCheck the scope table above. Card consent/subscription endpoints need client_recurringpaymentconsentrequest; terminal, store and terminal-session endpoints need client_terminal_session.
400 with field errorsInvalid request bodyCheck the field-level error messages in the response
Amount validation errorAmount below minimumAmounts 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:

RandsCents (API value)
R1.00100
R10.001000
R50.005000
R100.0010000
R1,000.00100000

Next Steps

  • Refunds: POST /api/v1/payment/{paymentId}/refund
  • Subscriptions: POST /api/v1/subscriptions (requires client_recurringpaymentconsentrequest scope)
  • Card Consents: POST /api/v1/card-consents (requires client_recurringpaymentconsentrequest scope)
  • Account Balance: GET /api/v1/account/balance
  • Withdraw Funds: POST /api/v1/withdrawal

See the full API reference at express.stitch.money/api-docs.