feat(core): type purchase return URLs [SAP-4059]

.changeset/purchase-return-url.md

@@ -0,0 +1,5 @@
+---
+"@sapiom/core": minor
+---
+
+Add optional transaction returnUrl types for returning to an integrator after hosted approval and card confirmation. Requires the corresponding backend deployment and a registered return destination.

packages/core/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @sapiom/core
 
+## Unreleased
+
+- Add optional transaction `returnUrl` for hosted purchase approval/card-confirmation return navigation. Destinations must be registered by the organization. Requires the corresponding backend deployment and package publication.
+
 ## 0.5.0
 
 ### Minor Changes

packages/core/README.md

@@ -154,6 +154,18 @@ await client.transactions.create({
 })
 ```
 
+##### Hosted purchase return navigation
+
+Pass `returnUrl` to `client.transactions.create(...)` to offer a return to your app after
+hosted approval and any required card confirmation. It may include your own opaque conversation
+reference, for example `https://your-app.example/conversations/123?state=opaque-reference`.
+Register HTTPS origins in organization metadata `paymentReturnOrigins`, or native app schemes
+(without the colon) in `paymentReturnSchemes`, through the organization PATCH API with `org.write`.
+The destination is stored per purchase, survives sign-in and revisions, and is opened only when
+the user clicks the return link. Sapiom adds no result parameters. Omission preserves the existing
+completion screen; read the transaction/checkout status before reporting payment success.
+Requires the corresponding backend deployment; native-link handling depends on the target device.
+
 ##### transactions.get()
 
 ```typescript

packages/core/src/types/transaction.ts

@@ -20,6 +20,8 @@ export interface TransactionCostInput {
 }
 
 export interface CreateTransactionRequest {
+  /** Return after hosted approval/card confirmation, using a registered organization destination. */
+  returnUrl?: string;
   requestFacts?: {
     source: string;
     version: string;
@@ -80,6 +82,7 @@ export interface TransactionCostResponse {
 }
 
 export interface TransactionResponse {
+  returnUrl?: string | null;
   id: string;
   organizationId: string;
   serviceName: string;