feat: add paymentInstruments and payment delegation

Author: kieran-osgood-shopify

modules/@shopify/checkout-sheet-kit/src/components/Checkout.tsx

@@ -118,14 +118,7 @@ interface NativeCheckoutWebViewProps {
     nativeEvent: CheckoutAddressChangeStart;
   }) => void;
   onPaymentMethodChangeStart?: (event: {
-    nativeEvent: {
-      id: string;
-      type: string;
-      currentCard?: {
-        last4: string;
-        brand: string;
-      };
-    };
+    nativeEvent: CheckoutPaymentMethodChangeStart;
   }) => void;
 }
 
@@ -259,13 +252,7 @@ export const Checkout = forwardRef<CheckoutRef, CheckoutProps>(
     const handlePaymentMethodChangeStart = useCallback<
       Required<NativeCheckoutWebViewProps>['onPaymentMethodChangeStart']
     >(
-      (event: {
-        nativeEvent: {
-          id: string;
-          type: string;
-          currentCard?: {last4: string; brand: string};
-        };
-      }) => {
+      event => {
         if (!event.nativeEvent) return;
         onPaymentMethodChangeStart?.(event.nativeEvent);
       },

modules/@shopify/checkout-sheet-kit/src/events.d.ts

@@ -46,6 +46,8 @@ export interface Cart {
   discountAllocations: CartDiscountAllocation[];
   /** Delivery addresses for the cart */
   delivery: CartDelivery;
+  /** Payment information for the cart */
+  payment: CartPayment;
 }
 
 /**
@@ -262,6 +264,25 @@ export interface CartDeliveryAddress {
  */
 export type CartAddress = CartDeliveryAddress;
 
+/**
+ * Payment instrument available for selection at checkout.
+ * Output type from Storefront API.
+ *
+ * @see https://shopify.dev/docs/api/storefront/latest/objects/CartPaymentInstrument
+ */
+export interface CartPaymentInstrument {
+  externalReference: string;
+}
+
+/**
+ * Payment information available for the cart.
+ *
+ * @see https://shopify.dev/docs/api/storefront/latest/objects/CartPayment
+ */
+export interface CartPayment {
+  instruments: CartPaymentInstrument[];
+}
+
 /**
  * Discount applied to a cart line or the entire cart.
  * Shows how much was discounted and which code/promotion applied it.
@@ -474,6 +495,11 @@ export interface CartInput {
    * Optional - use to apply discount codes to the cart.
    */
   discountCodes?: string[];
+  /**
+   * Payment instruments for the cart.
+   * Optional - use to update payment methods.
+   */
+  paymentInstruments?: CartPaymentInstrumentInput[];
 }
 
 /**
@@ -592,8 +618,6 @@ export interface CheckoutPaymentMethodChangeStart {
   id: string;
   /** Type of payment change event */
   type: 'paymentMethodChangeStart';
-  /** Cart state with current payment instruments */
-  cart?: {
-    paymentInstruments?: CartPaymentInstrumentInput[];
-  };
+  /** Cart state when the event was emitted */
+  cart: Cart;
 }

modules/@shopify/checkout-sheet-kit/src/index.ts

@@ -503,6 +503,8 @@ export type {
   CartDeliveryInput,
   CartInput,
   CardBrand,
+  CartPayment,
+  CartPaymentInstrument,
   CartPaymentInstrumentDisplayInput,
   CartPaymentInstrumentInput,
   CheckoutAddressChangeStart,

modules/@shopify/checkout-sheet-kit/tests/testFixtures.ts

@@ -69,6 +69,9 @@ export function createTestCart(overrides?: Partial<Cart>): Cart {
         },
       ],
     },
+    payment: {
+      instruments: [],
+    },
     ...overrides,
   };
 }

sample/ios/Podfile.lock

@@ -2891,6 +2891,6 @@ SPEC CHECKSUMS:
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Yoga: a742cc68e8366fcfc681808162492bc0aa7a9498
 
-PODFILE CHECKSUM: c18c67add5bb02cbc43b46941cc12b33c4a7572f
+PODFILE CHECKSUM: e096ca5df616e23383b3aad99d7484917ddb6df1
 
 COCOAPODS: 1.15.2

sample/src/screens/BuyNow/CheckoutScreen.tsx

@@ -24,6 +24,7 @@ import {
   Checkout,
   type CheckoutAddressChangeStart,
   type CheckoutCompleteEvent,
+  type CheckoutPaymentMethodChangeStart,
   type CheckoutRef,
   type CheckoutStartEvent,
 } from '@shopify/checkout-sheet-kit';
@@ -47,7 +48,8 @@ export default function CheckoutScreen(props: {
     navigation.navigate('Address', {id: event.id});
   };
 
-  const onPaymentMethodChangeStart = (event: {id: string}) => {
+  const onPaymentMethodChangeStart = (event: CheckoutPaymentMethodChangeStart) => {
+    console.log('<CheckoutScreen /> onPaymentMethodChangeStart: ', event);
     navigation.navigate('Payment', {id: event.id});
   };
 

sample/src/screens/BuyNow/PaymentScreen.tsx

@@ -21,7 +21,13 @@ import type {RouteProp} from '@react-navigation/native';
 import {useNavigation, useRoute} from '@react-navigation/native';
 import React from 'react';
 import {Button, StyleSheet, Text, TouchableOpacity, View} from 'react-native';
-import {useShopifyEvent} from '@shopify/checkout-sheet-kit';
+import {
+  useShopifyEvent,
+  type CardBrand,
+  type CartInput,
+  type CartPaymentInstrumentInput,
+  type MailingAddressInput,
+} from '@shopify/checkout-sheet-kit';
 import {useCart} from '../../context/Cart';
 import type {BuyNowStackParamList} from './types';
 
@@ -31,68 +37,96 @@ export default function PaymentScreen() {
   const event = useShopifyEvent(route.params.id);
   const {selectedPaymentIndex, setSelectedPaymentIndex} = useCart();
 
-  const paymentOptions = [
+  const paymentOptions: Array<{
+    id: string;
+    label: string;
+    cardHolderName: string;
+    last4: string;
+    brand: CardBrand;
+    expiry: {month: number; year: number};
+    billingAddress: MailingAddressInput;
+  }> = [
     {
+      id: 'card-personal-visa-4242',
       label: 'Personal Visa',
-      card: {
-        last4: '4242',
-        brand: 'Visa',
-      },
-      billing: {
-        useDeliveryAddress: true,
+      cardHolderName: 'John Doe',
+      last4: '4242',
+      brand: 'VISA',
+      expiry: {month: 12, year: 2028},
+      billingAddress: {
+        firstName: 'John',
+        lastName: 'Doe',
+        address1: '123 Main St',
+        city: 'San Francisco',
+        provinceCode: 'CA',
+        countryCode: 'US',
+        zip: '94102',
       },
     },
     {
+      id: 'card-business-mc-5555',
       label: 'Business MasterCard',
-      card: {
-        last4: '5555',
-        brand: 'Mastercard',
-      },
-      billing: {
-        useDeliveryAddress: true,
+      cardHolderName: 'Jane Smith',
+      last4: '5555',
+      brand: 'MASTERCARD',
+      expiry: {month: 6, year: 2027},
+      billingAddress: {
+        firstName: 'Jane',
+        lastName: 'Smith',
+        address1: '456 Market St',
+        city: 'San Francisco',
+        provinceCode: 'CA',
+        countryCode: 'US',
+        zip: '94103',
       },
     },
     {
+      id: 'card-corporate-amex-0005',
       label: 'Corporate Amex',
-      card: {
-        last4: '0005',
-        brand: 'American Express',
-      },
-      billing: {
-        useDeliveryAddress: false,
-        address: {
-          firstName: 'Corporate',
-          lastName: 'Billing',
-          address1: '123 Business Blvd',
-          address2: 'Suite 500',
-          city: 'New York',
-          provinceCode: 'NY',
-          countryCode: 'US',
-          zip: '10001',
-          phone: '+1-212-555-0100',
-          company: 'Acme Corporation',
-        },
+      cardHolderName: 'Corporate Account',
+      last4: '0005',
+      brand: 'AMERICAN_EXPRESS',
+      expiry: {month: 3, year: 2026},
+      billingAddress: {
+        firstName: 'Corporate',
+        lastName: 'Billing',
+        address1: '123 Business Blvd',
+        address2: 'Suite 500',
+        city: 'New York',
+        provinceCode: 'NY',
+        countryCode: 'US',
+        zip: '10001',
+        phone: '+1-212-555-0100',
+        company: 'Acme Corporation',
       },
     },
   ];
 
-  const handlePaymentSelection = () => {
+  const handlePaymentSelection = async () => {
     const selectedPayment = paymentOptions[selectedPaymentIndex];
-    event.respondWith({
-      card: selectedPayment!.card,
-      billing: selectedPayment!.billing,
-    });
+    if (!selectedPayment) return;
+
+    const paymentInstrument: CartPaymentInstrumentInput = {
+      externalReference: selectedPayment.id,
+      display: {
+        last4: selectedPayment.last4,
+        brand: selectedPayment.brand,
+        cardHolderName: selectedPayment.cardHolderName,
+        expiry: selectedPayment.expiry,
+      },
+      billingAddress: selectedPayment.billingAddress,
+    };
+
+    const response: CartInput = {
+      paymentInstruments: [paymentInstrument],
+    };
+
+    await event.respondWith(response);
     navigation.goBack();
   };
 
-  const getCardIcon = (brand: string) => {
-    // In a real app, you'd use actual card brand icons
-    const brandIcons: {[key: string]: string} = {
-      'Visa': '💳',
-      'Mastercard': '💳',
-      'American Express': '💳',
-    };
-    return brandIcons[brand] || '💳';
+  const getCardIcon = (_brand: CardBrand) => {
+    return '💳';
   };
 
   return (
@@ -116,16 +150,14 @@ export default function PaymentScreen() {
             </View>
             <View style={styles.paymentInfo}>
               <View style={styles.cardHeader}>
-                <Text style={styles.cardIcon}>{getCardIcon(option.card.brand)}</Text>
+                <Text style={styles.cardIcon}>{getCardIcon(option.brand)}</Text>
                 <Text style={styles.paymentLabel}>{option.label}</Text>
               </View>
               <Text style={styles.cardDetails}>
-                {option.card.brand} •••• {option.card.last4}
+                {option.brand} •••• {option.last4}
               </Text>
               <Text style={styles.billingInfo}>
-                {option.billing.useDeliveryAddress
-                  ? 'Uses delivery address'
-                  : `Separate billing: ${option.billing.address?.city}, ${option.billing.address?.provinceCode}`}
+                {option.billingAddress.city}, {option.billingAddress.provinceCode}
               </Text>
             </View>
           </TouchableOpacity>