@moonpay/platform-sdk-react-native 1.31.1 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -183,7 +183,7 @@ All client methods return a `Result<T, E>` discriminated union instead of throwi
183
183
  | `active` | Customer is connected | Proceed — quotes, payment methods, and payment frames are ready to use |
184
184
  | `pending` | KYC decision is delayed | Show a waiting state; the status can resolve to `active` on a later visit |
185
185
  | `failed` | Terminal failure, such as a KYC rejection | Do not retry the connect flow; the `reason` field describes the failure |
186
- | `unavailable` | Customer is in a restricted location | Hide MoonPay functionality |
186
+ | `unavailable` | The customer can't use MoonPay right now. The status doesn't say why | Show a general message that points the customer to MoonPay support. Don't tell the customer their region isn't supported |
187
187
  | `termsAcceptanceRequired` | Headless integrations only — the customer has no valid Terms of Use attestation on file | Show the Terms of Use in your UI, capture acceptance via `POST /platform/v1/terms/attestations`, then check the connection again |
188
188
 
189
189
  ## Two ways to render frames
@@ -325,6 +325,39 @@ import { MoonPayBuyButton } from '@moonpay/platform-sdk-react-native';
325
325
 
326
326
  `<MoonPayApplePayButton>` and `<MoonPayGooglePayButton>` are deprecated: the Apple Pay and Google Pay frames are being removed. Render `<MoonPayBuyButton>` instead.
327
327
 
328
+ ### Payment methods that open another app
329
+
330
+ Some payment methods hand the customer to another app to approve the payment. Cash App Pay is one example. When the customer taps the button, the buy button frame asks your app to open a link, and the SDK passes this to you as a `challenge` event whose `payload.kind` is `'link_payment_method'`. Your app opens the link.
331
+
332
+ ```tsx
333
+ <MoonPayBuyButton
334
+ quote={quoteSignature}
335
+ linkReturnUrl="myapp://moonpay-return"
336
+ onEvent={(event) => {
337
+ if (event.kind !== 'challenge' || event.payload.kind !== 'link_payment_method') return;
338
+ const { paymentMethod, url } = event.payload;
339
+ if (isTrustedLink(paymentMethod, url)) Linking.openURL(url);
340
+ }}
341
+ />
342
+ ```
343
+
344
+ - **Check the link first.** Only open an `https` link on a host you trust for the payment method. For `cash_app` that is `cash.app`, `cash.me` and `sandbox.api.cash.app`. Compare the parsed host exactly, and never open anything else. Never open `linkReturnUrl`.
345
+ - **The customer can try again.** Tapping the button while it is connecting cancels. Tapping again starts over, and you receive another `challenge` event with a fresh link. If your app doesn't open the link, the button keeps showing "Connecting" until the customer cancels or it times out.
346
+ - **No native setup.** `Linking.openURL` opens the other app if installed and the browser if not, so no Info.plist entry or Android manifest change is needed.
347
+ - **`linkReturnUrl`** (optional) brings the customer back to your app: an absolute URL such as a deep link. Without it the customer switches back themselves, and the button still updates once the payment method is saved. It is mount-time only.
348
+ - **Check `payload.kind`.** A `challenge` event is either a frame challenge (`'frame'`: load `url` in a challenge frame) or this one. Never open a `link_payment_method` URL in a challenge frame.
349
+ - Offer a payment method that opens another app only when your app handles this event. This needs `@moonpay/platform-sdk-react-native` 1.32.0 or later.
350
+
351
+ #### Frame message contract
352
+
353
+ For a manual integration, the frame sends one message to your host, using the envelope `{ version: 2, meta: { channelId }, kind, payload }`.
354
+
355
+ | Direction | `kind` | `payload` |
356
+ | --- | --- | --- |
357
+ | Frame to host | `challenge` | `{ kind: 'link_payment_method'; paymentMethod: 'cash_app'; url: string }` |
358
+
359
+ The frame URL also carries `linkReturnUrl` when you set one.
360
+
328
361
  ### Execute a buy headlessly
329
362
 
330
363
  `<MoonPayBuyFrame>` executes a buy in a hidden WebView — your own UI stays in control the whole time. It needs an executable quote: one created with a `wallet` and `paymentMethod`. Render the frame when the customer confirms the purchase:
package/dist/index.cjs CHANGED
@@ -56,6 +56,17 @@ var import_connection2 = require("@moonpay/platform-protocol/models/connection")
56
56
  // src/frame-specs.ts
57
57
  var import_connection = require("@moonpay/platform-protocol/models/connection");
58
58
  var import_platform_sdk_core = require("@moonpay/platform-sdk-core");
59
+
60
+ // src/return-url.ts
61
+ var MAX_URL_LENGTH = 2048;
62
+ var UNSAFE_RETURN_URL_SCHEMES = /* @__PURE__ */ new Set(["javascript", "data", "file", "vbscript", "blob"]);
63
+ function isValidReturnUrl(value) {
64
+ if (typeof value !== "string" || value.length > MAX_URL_LENGTH) return false;
65
+ const scheme = /^([a-z][a-z0-9+.-]*):\S+$/i.exec(value)?.[1];
66
+ return scheme !== void 0 && !UNSAFE_RETURN_URL_SCHEMES.has(scheme.toLowerCase());
67
+ }
68
+
69
+ // src/frame-specs.ts
59
70
  function createQuoteCommands(send, channelId) {
60
71
  return {
61
72
  setQuote: (signature) => send({
@@ -165,12 +176,11 @@ var googlePaySpec = {
165
176
  },
166
177
  errorEvent: (message) => ({ kind: "error", payload: { kind: "genericError", message } })
167
178
  };
168
- var buyButtonSpec = {
169
- channelPrefix: "buy-button",
170
- path: import_platform_sdk_core.FRAME_PATHS.buyButton,
171
- enterprise: true,
172
- hidden: false,
173
- buildParams: (ctx, props) => ({
179
+ function buyButtonParams(ctx, props) {
180
+ if (props.linkReturnUrl !== void 0 && !isValidReturnUrl(props.linkReturnUrl)) {
181
+ throw new Error("linkReturnUrl must be an absolute URL, for example myapp://moonpay-return");
182
+ }
183
+ return {
174
184
  clientToken: ctx.core.context.clientToken,
175
185
  signature: props.quote,
176
186
  ...props.externalTransactionId && { externalTransactionId: props.externalTransactionId },
@@ -178,8 +188,16 @@ var buyButtonSpec = {
178
188
  ...props.googlePayButtonSettings && {
179
189
  googlePayButtonSettings: props.googlePayButtonSettings
180
190
  },
191
+ ...props.linkReturnUrl && { linkReturnUrl: props.linkReturnUrl },
181
192
  ...(0, import_platform_sdk_core.presentationParams)(props.presentation)
182
- }),
193
+ };
194
+ }
195
+ var buyButtonSpec = {
196
+ channelPrefix: "buy-button",
197
+ path: import_platform_sdk_core.FRAME_PATHS.buyButton,
198
+ enterprise: true,
199
+ hidden: false,
200
+ buildParams: (ctx, props) => buyButtonParams(ctx, props),
183
201
  createCommands: createQuoteCommands,
184
202
  reactiveProps: {
185
203
  quote: (commands, quote) => commands.setQuote(quote)
@@ -217,7 +235,7 @@ var headlessBuyButtonSpec = {
217
235
  ...buyButtonSpec,
218
236
  hidden: true,
219
237
  buildParams: (ctx, props) => ({
220
- ...buyButtonSpec.buildParams?.(ctx, props),
238
+ ...buyButtonParams(ctx, props),
221
239
  headless: true
222
240
  })
223
241
  };
@@ -856,7 +874,8 @@ async function setupBuyButton(deps, opts) {
856
874
  externalTransactionId: opts.externalTransactionId,
857
875
  applePayButtonSettings: opts.applePayButtonSettings,
858
876
  googlePayButtonSettings: opts.googlePayButtonSettings,
859
- presentation: opts.presentation
877
+ presentation: opts.presentation,
878
+ linkReturnUrl: opts.linkReturnUrl
860
879
  }
861
880
  );
862
881
  handle.onEvent((event) => opts.onEvent?.(event));
@@ -1600,6 +1619,7 @@ function MoonPayBuyButton({
1600
1619
  externalTransactionId,
1601
1620
  applePayButtonSettings,
1602
1621
  googlePayButtonSettings,
1622
+ linkReturnUrl,
1603
1623
  headless,
1604
1624
  onEvent,
1605
1625
  style,
@@ -1609,7 +1629,13 @@ function MoonPayBuyButton({
1609
1629
  MoonPayFrameView,
1610
1630
  {
1611
1631
  spec: headless ? headlessBuyButtonSpec : buyButtonSpec,
1612
- props: { quote, externalTransactionId, applePayButtonSettings, googlePayButtonSettings },
1632
+ props: {
1633
+ quote,
1634
+ externalTransactionId,
1635
+ applePayButtonSettings,
1636
+ googlePayButtonSettings,
1637
+ linkReturnUrl
1638
+ },
1613
1639
  style,
1614
1640
  defaultStyle: { height: 48 },
1615
1641
  onEvent,