[ynadge]

Primary change type

• Bug fix
• Documentation
• Feature
• Tests
• Dependency update
• Maintenance or refactor

Problem and motivation

Integrators need a typed return destination when opening Sapiom's hosted purchase approval and card-confirmation flow from another app.

Summary and scope

Add optional returnUrl fields to the existing transaction create/response types, with integration guidance, release notes and a minor Changeset. The existing client already forwards the request body; destination validation, persistence and hosted navigation are implemented by the companion backend.

Related work

Requested follow-up to SAP-4059. Backend/UI: https://github.com/sapiom/Sapiom/pull/5938.

Validation

pnpm --filter @sapiom/core typecheck — passed
pnpm --filter @sapiom/core build — passed (CommonJS and ESM)
pnpm --filter @sapiom/core exec jest --runInBand — 132 tests passed
pnpm --filter @sapiom/core exec prettier --check src/types/transaction.ts — passed
git diff --check — passed

Tests and documentation

Core's existing tests pass. No runtime code changes or new transport logic; the backend companion tests the approval/CVV return behavior. README and CHANGELOG document registration, per-purchase context and payment-status semantics. Root workspace checks were scoped to the affected core package.

Compatibility and release impact

• Breaking or externally visible changes: additive optional fields; deploy the companion backend before using the option, and publish core before relying on the new types.
• Changeset: purchase-return-url.md (@sapiom/core, minor).

Security

• I have not included secrets, credentials, private data, or unsanitized logs.
• This pull request does not publicly disclose a suspected vulnerability.

AI assistance

• I did not use AI assistance for this change.
• I used AI assistance and have described it below.

Codex added the optional fields and documentation and verified the package build, type check, tests and formatting.

Checklist

• I read CONTRIBUTING.md; this implements the maintainer-requested return navigation contract.
• This pull request addresses one focused problem and contains no unrelated cleanup.
• I added or updated tests, or explained above why tests are not applicable.
• I ran the relevant checks or explained the scope above.
• I updated documentation for user-facing changes.
• I added a Changeset for a published-package change.
• I can explain and maintain every submitted change, including AI-assisted work.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}