expo-pay 0.1.1 → 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# expo-pay
+
+Android Google Pay for Expo native apps.
+
+`expo-pay` provides an Expo native module and native view for rendering the
+official Google Pay button, checking `isReadyToPay`, and presenting the Android
+Google Pay payment sheet. It does not process payments or talk to your backend:
+you provide the Google Pay request JSON for your gateway, and your server or
+payment provider handles the returned token.
+
+Apple Pay is intentionally not implemented yet.
+
+## Installation
+
+```sh
+npm install expo-pay
+```
+
+This package contains Android native code, so it must be used in an Expo
+development build or a prebuilt/bare React Native app. It will not run inside
+Expo Go.
+
+```sh
+npx expo prebuild
+npx expo run:android
+```
+
+The Android module includes the Google Pay manifest metadata required by
+Google:
+
+```xml
+<meta-data
+  android:name="com.google.android.gms.wallet.api.enabled"
+  android:value="true" />
+```
+
+## Basic Usage
+
+```tsx
+import GooglePayButton, { isReadyToPayAsync } from "expo-pay";
+import { useRef, useState } from "react";
+import type { GooglePayButtonRef } from "expo-pay";
+
+const baseCardPaymentMethod = {
+  type: "CARD",
+  parameters: {
+    allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
+    allowedCardNetworks: ["AMEX", "DISCOVER", "MASTERCARD", "VISA"],
+  },
+};
+
+const paymentRequest = {
+  apiVersion: 2,
+  apiVersionMinor: 0,
+  allowedPaymentMethods: [
+    {
+      ...baseCardPaymentMethod,
+      tokenizationSpecification: {
+        type: "PAYMENT_GATEWAY",
+        parameters: {
+          gateway: "example",
+          gatewayMerchantId: "exampleGatewayMerchantId",
+        },
+      },
+    },
+  ],
+  merchantInfo: {
+    merchantName: "Example Merchant",
+  },
+  transactionInfo: {
+    totalPriceStatus: "FINAL",
+    totalPrice: "10.00",
+    currencyCode: "USD",
+    countryCode: "US",
+  },
+};
+
+const isReadyToPayRequest = {
+  apiVersion: 2,
+  apiVersionMinor: 0,
+  allowedPaymentMethods: [baseCardPaymentMethod],
+};
+
+export function Checkout() {
+  const ref = useRef<GooglePayButtonRef>(null);
+  const [ready, setReady] = useState<boolean | null>(null);
+
+  async function checkReadiness() {
+    setReady(await isReadyToPayAsync(isReadyToPayRequest));
+  }
+
+  return (
+    <GooglePayButton
+      ref={ref}
+      style={{ height: 48, width: "100%" }}
+      paymentRequest={paymentRequest}
+      isReadyToPayRequest={isReadyToPayRequest}
+      environment="TEST"
+      buttonTheme="dark"
+      buttonType="buy"
+      onReadyToPayChanged={({ nativeEvent }) => {
+        setReady(nativeEvent.isReadyToPay);
+      }}
+      onTokenReceived={({ nativeEvent }) => {
+        // Send nativeEvent.token to your backend/payment gateway.
+      }}
+      onCancel={() => {}}
+      onError={({ nativeEvent }) => {
+        console.warn(nativeEvent.code, nativeEvent.message);
+      }}
+    />
+  );
+}
+```
+
+## API
+
+### `isReadyToPayAsync(request, environment?)`
+
+Checks whether Google Pay is available for the supplied request.
+
+- `request`: raw Google Pay `IsReadyToPayRequest` JSON as a string or object.
+- `environment`: `"TEST"` or `"PRODUCTION"`. Defaults to `"TEST"`.
+- Returns `false` on unsupported platforms.
+
+### `GooglePayButton`
+
+Renders the native Google Pay button and presents the payment sheet when
+pressed.
+
+Props:
+
+- `paymentRequest`: required Google Pay `PaymentDataRequest` JSON as a string or
+  object.
+- `isReadyToPayRequest`: optional explicit readiness request. If omitted, the
+  module derives one from `paymentRequest.allowedPaymentMethods`.
+- `environment`: `"TEST"` or `"PRODUCTION"`. Defaults to `"TEST"`.
+- `buttonTheme`: `"dark"` or `"light"`.
+- `buttonType`: `"book"`, `"buy"`, `"checkout"`, `"donate"`, `"ewallet"`,
+  `"order"`, `"pay"`, `"pix"`, `"plain"`, or `"subscribe"`.
+- `cornerRadius`: native Google Pay button corner radius.
+- `disabled`: disables button presses.
+- `existingPaymentMethodRequired`: adds
+  `existingPaymentMethodRequired: true` to the derived readiness request.
+- `autoCheckReadiness`: checks readiness after prop updates. Defaults to `true`.
+- `hideWhenNotReady`: hides the button when readiness is `false`.
+
+Events:
+
+- `onReadyToPayChanged`: `{ isReadyToPay }`
+- `onTokenReceived`: `{ token, paymentData, paymentMethodData, paymentMethodType,
+cardNetwork, cardDetails, email }`
+- `onCancel`
+- `onError`: `{ code, message, nativeMessage, statusCode, statusMessage }`
+
+Ref methods:
+
+- `presentPaymentSheet(): Promise<void>`
+- `checkReadiness(): Promise<void>`
+
+## TEST and PRODUCTION
+
+Use `"TEST"` while developing. Google's TEST environment returns fake,
+non-chargeable payment credentials and does not require a Google Pay merchant
+approval.
+
+Before using `"PRODUCTION"`:
+
+- Replace the example gateway values with your payment processor values.
+- Use your real Google Pay merchant name and merchant ID where required.
+- Complete Google's production access and integration checklist.
+- Distribute the Android app through a production-signed build; Google Pay
+  production integrations are reviewed by Google.
+
+Google references:
+
+- [Android setup](https://developers.google.com/pay/api/android/guides/setup)
+- [Android tutorial](https://developers.google.com/pay/api/android/guides/tutorial)
+- [Test and deploy](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist)
+
+Expo references:
+
+- [Native module tutorial](https://docs.expo.dev/modules/native-module-tutorial/)
+- [Native view tutorial](https://docs.expo.dev/modules/native-view-tutorial/)
+- [Module config](https://docs.expo.dev/modules/module-config/)
+
+## Troubleshooting
+
+`Cannot find native module 'ExpoGooglePay'`
+
+Rebuild the native app after installing the package:
+
+```sh
+npx expo prebuild
+npx expo run:android
+```
+
+`GooglePayButton is only available on Android`
+
+This package currently implements Android Google Pay only. Guard rendering with
+`Platform.OS === "android"` in shared screens.
+
+`ERR_GOOGLE_PAY_INVALID_REQUEST`
+
+The request JSON could not be parsed by Google Pay. Validate the shape against
+Google's `PaymentDataRequest` and `IsReadyToPayRequest` docs.
+
+`ERR_GOOGLE_PAY_READY_TO_PAY`
+
+The readiness check failed at the Google Pay API layer. Check Google Play
+services availability, Android emulator/device configuration, and request JSON.

package/android/build.gradle

@@ -3,16 +3,20 @@ plugins {
   id 'expo-module-gradle-plugin'
 }
 
-group = 'expo.modules.pay'
-version = '0.1.0'
+group = 'expo.modules.googlepay'
+version = '0.1.1'
 
 android {
-  namespace "expo.modules.pay"
+  namespace "expo.modules.googlepay"
   defaultConfig {
     versionCode 1
-    versionName "0.1.0"
+    versionName "0.1.1"
   }
   lintOptions {
     abortOnError false
   }
 }
+
+dependencies {
+  implementation "com.google.android.gms:play-services-wallet:20.0.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,7 @@
-<manifest>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <meta-data
+      android:name="com.google.android.gms.wallet.api.enabled"
+      android:value="true" />
+  </application>
 </manifest>

package/android/src/main/java/expo/modules/googlepay/ExpoGooglePayModule.kt

@@ -0,0 +1,119 @@
+package expo.modules.googlepay
+
+import com.google.android.gms.wallet.IsReadyToPayRequest
+import com.google.android.gms.wallet.Wallet
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import org.json.JSONException
+
+class ExpoGooglePayModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("ExpoGooglePay")
+
+    AsyncFunction("isReadyToPayAsync") { requestJson: String, environment: String?, promise: Promise ->
+      val request = try {
+        IsReadyToPayRequest.fromJson(requestJson)
+      } catch (exception: JSONException) {
+        promise.reject("ERR_GOOGLE_PAY_INVALID_REQUEST", "Invalid IsReadyToPayRequest JSON.", exception)
+        return@AsyncFunction
+      }
+
+      val activity = appContext.currentActivity
+      if (activity == null) {
+        promise.reject(Exceptions.MissingActivity())
+        return@AsyncFunction
+      }
+
+      val paymentsClient = Wallet.getPaymentsClient(
+        activity,
+        Wallet.WalletOptions.Builder()
+          .setEnvironment(parseGooglePayEnvironment(environment))
+          .build()
+      )
+
+      paymentsClient.isReadyToPay(request)
+        .addOnCompleteListener { task ->
+          if (task.isSuccessful) {
+            promise.resolve(task.result == true)
+          } else {
+            promise.reject(
+              "ERR_GOOGLE_PAY_READY_TO_PAY",
+              task.exception?.localizedMessage ?: "Google Pay readiness check failed.",
+              task.exception
+            )
+          }
+        }
+    }
+
+    OnActivityResult { _, (requestCode, resultCode, data) ->
+      PendingGooglePayPayment.handleActivityResult(requestCode, resultCode, data)
+    }
+
+    View(ExpoGooglePayView::class) {
+      Events(
+        "onTokenReceived",
+        "onError",
+        "onCancel",
+        "onReadyToPayChanged"
+      )
+
+      Prop("paymentRequestJson") { view: ExpoGooglePayView, paymentRequestJson: String? ->
+        view.paymentRequestJson = paymentRequestJson
+      }
+
+      Prop("isReadyToPayRequestJson") { view: ExpoGooglePayView, isReadyToPayRequestJson: String? ->
+        view.isReadyToPayRequestJson = isReadyToPayRequestJson
+      }
+
+      Prop("environment") { view: ExpoGooglePayView, environment: String? ->
+        view.environment = environment
+      }
+
+      Prop("buttonTheme") { view: ExpoGooglePayView, buttonTheme: String? ->
+        view.buttonTheme = buttonTheme
+      }
+
+      Prop("buttonType") { view: ExpoGooglePayView, buttonType: String? ->
+        view.buttonType = buttonType
+      }
+
+      Prop("cornerRadius") { view: ExpoGooglePayView, cornerRadius: Double? ->
+        view.cornerRadius = cornerRadius
+      }
+
+      Prop("disabled") { view: ExpoGooglePayView, disabled: Boolean? ->
+        view.disabled = disabled == true
+      }
+
+      Prop("existingPaymentMethodRequired") { view: ExpoGooglePayView, existingPaymentMethodRequired: Boolean? ->
+        view.existingPaymentMethodRequired = existingPaymentMethodRequired == true
+      }
+
+      Prop("autoCheckReadiness") { view: ExpoGooglePayView, autoCheckReadiness: Boolean? ->
+        view.autoCheckReadiness = autoCheckReadiness != false
+      }
+
+      Prop("hideWhenNotReady") { view: ExpoGooglePayView, hideWhenNotReady: Boolean? ->
+        view.hideWhenNotReady = hideWhenNotReady == true
+      }
+
+      AsyncFunction("presentPaymentSheet") { view: ExpoGooglePayView ->
+        view.presentPaymentSheet()
+      }
+
+      AsyncFunction("checkReadiness") { view: ExpoGooglePayView ->
+        view.checkReadiness()
+      }
+
+      OnViewDidUpdateProps { view: ExpoGooglePayView ->
+        view.onPropsUpdated()
+      }
+
+      OnViewDestroys { view: ExpoGooglePayView ->
+        PendingGooglePayPayment.clear(view)
+      }
+    }
+  }
+}