AUTH4D-36: Stitch payment links and status lookup

@auth4/provider-stitch exports createStitchPaymentsClient({ api, onWarning? }), built on the AUTH4D-35 REST transport. The token client needs the client_paymentrequest scope. The package exposes no HTTP routes.

createPaymentRequest

The input is { paymentId, amount, payerName, redirectUrl, expiresAt? }. The call sends POST /api/v1/payment-links as operation CreatePaymentLink and returns { providerPaymentId, redirectUrl }. providerPaymentId is the Express payment link id.

• amount is a contract Money. Express takes integer South African cents, so amountMinor is sent as is. The currency must be ZAR and the amount at least 100 (R1.00).
• merchantReference is our paymentId with a hyphen (pay_abc… is sent as pay-abc…), because Express allows only letters, digits, spaces and hyphens there. Status lookups and the payer’s return correlate to our payment record through it.
• payerName is shown on the Stitch checkout page. It must be 3 to 40 printable ASCII characters.
• redirectUrl must be HTTPS, or HTTP on loopback. It is appended to the Stitch-hosted link as the redirect_url query parameter, and the result’s redirectUrl is that combined URL. Stitch only honours a registered redirect URL (at most 5 per account), compared without its query string; an unregistered one shows the payer a 404. Register it with infra/stitch/setup.mjs. On return Stitch appends reference (the merchant reference) and its own payment_id.
• expiresAt (ISO 8601) is sent when present. Express defaults to 30 days.
• A response whose amount differs from the requested amount is an upstream error, so a link for a different amount never reaches the payer.

getPaymentStatus

getPaymentStatus(providerPaymentId) sends GET /api/v1/payment-links/{id} as operation GetPaymentLink. It returns { providerPaymentId, status, providerState?, externalReference? }.

The warning is { code: "unknown_payment_state", operationName, providerState? }. providerState is included only when it is a plain identifier. The warning goes to onWarning, or by default to console.warn as one JSON line with event provider.stitch.payment.

externalReference is our payment id recovered from the link’s merchantReference, or the raw reference when it is not one of ours. Callers must check that it equals the payment they expect before acting on the result.

Errors

All failures are StitchError:

• validation: invalid input, which is rejected before any HTTP call; a Stitch field error; an unknown link id (HTTP 404); or a response for a different id.
• upstream: a malformed response, or a link created for a different amount.
• Transport errors are unchanged from AUTH4D-35.