sumup-react-native

SumUp's React Native Payment SDK provides a payment sheet that is displayed on top of your app. It collects user payment details, confirms a payment, and saves a card for future usage. Moreover, it allows a user to use Apple Pay or Google Pay to process payments.

Before you begin

Here are the things that you need in order to complete the steps in this guide:

You have a merchant account with SumUp and have already filled in your account details.
- For a test account reach out to our support team through this contact form.
You have registered your client application with SumUp.
You have a valid access token obtained via the Authorization code flow.
The restricted payment_instruments scope is enabled for your client application. If it isn't enabled, contact us and request it.
Review how to create a single payment here.

Prerequirement

The initial requirements describe there https://developer.sumup.com/docs/online-payments/guides/single-payment/#before-you-begin

You would need to create a checkout on your backend, then fetch checkout id and init an sdk with this identifier.

Payment sheet

SDK will process this checkout if a user provides card details. Otherwise, you receive an error.

Checkout can be created by the following request:

curl --request POST \
 --url https://api.sumup.com/v0.1/checkouts \
 --header 'Authorization: Bearer <API KEY>' \
 --header 'Content-Type: application/json' \
 --data '{
"checkout_reference": "44ea5096-b83f-46e1-9323-fe82a8cb7eb5",
"currency": "SEK",
"amount": 9.99,
"description": "Order #1234",
"merchant_code": "<MERCHANT CODE>",
"return_url": "https://example.com",
"redirect_url": "https://sumup.com"
}'

Save Card sheet

For saving cards, the flow is similar. The only difference is that the checkout should be created with a specific purpose. If the purpose is not passed, the SDK will return an error.

Checkout can be created by the following request:

curl --request POST \
 --url https://api.sumup.com/v0.1/checkouts \
 --header 'Authorization: Bearer <API KEY>' \
 --header 'Content-Type: application/json' \
 --data '{
"checkout_reference": "44ea5096-b83f-46e1-9323-fe82a8cb7eb5",
"currency": "SEK",
"amount": 9.99,
"description": "Order #1234",
"merchant_code": "<MERCHANT CODE>",
"return_url": "https://example.com",
"redirect_url": "https://sumup.com",
"purpose": "setup_recurring_payment"
}'

Create a customer

A customer should be created to save the card for future usage.

NOTE: It's required for the Save Card sheet (which is used only for saving card details).

NOTE: It can be used in the Payment sheet to save a card for future usage. Additional information is below.

curl -L -X POST 'https://api.sumup.com/v0.1/customers' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"customer_id": "831ff8d4cd5958ab5670",
"personal_details": {
"first_name": "John",
"last_name": "Doe",
"email": "user@example.com",
"phone": "+491635559723",
"birthdate": "1993-12-31",
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Sample street",
"line2": "ap. 5",
"postal_code": "10115",
"state": "Berlin"
}
}
}'

More information about it you can find on the website.

Installation

yarn add sumup-react-native-alpha
yarn add react-native-webview react-native-safe-area-context @react-native-community/netinfo

or

npm i sumup-react-native-alpha
npm i react-native-webview react-native-safe-area-context @react-native-community/netinfo

You need to add fonts. For this create a react-native.config.js file in a root folder and put the following content:

module.exports = {
  dependecies: {},
  project: {
    ios: {},
    android: {},
  },
  assets: ['./node_modules/sumup-react-native-alpha/src/assets/fonts'],
};

Then run the following command if your React Native version is below 0.69:

npx react-native link

or

yarn react-native link

or if the version is older than 0.69:

npx react-native-asset

You also need to install react-native-localization to automatically detect user system language. If you don't need it, please provide the language field in the initPaymentSheet function.

yarn add react-native-localization

or

npm i react-native-localization

await initPaymentSheet({
  checkoutId,
  language: 'en',
});

iOS

Install native modules

cd ios
pod install

Usage

import { SumUpProvider } from 'sumup-react-native-alpha';

export default function App() {
  return (
    <SumUpProvider publicKey="sup_pk_...">
      <Screen />
    </SumUpProvider>
  );
}

Payment sheet

...
import { useSumUp } from 'sumup-react-native-alpha';

export default function Screen() {
  const { initPaymentSheet, presentPaymentSheet } = useSumUp();

  useEffect(() => {
    initPayment();
  }, []);

  const initPayment = async () => {
    const res = await initPaymentSheet({
      checkoutId: '...',
    });

    console.log(res);
  };

  const onPress = async () => {
    const res = await presentPaymentSheet();
    console.log(res);
  };

  return (
    <TouchableOpacity onPress={onPress}>
      <Text>Show payment sheet</Text>
    </TouchableOpacity>
  );
}

NOTE: React Native has a known problem regarding showing 2 modals simultaneously. If you need to show an SDK from a modal, add a PaymentSheet component inside your modal.

...
import { PaymentSheet } from 'sumup-react-native-alpha';

export default function Screen() {
  ...

  return (
    <Modal>
      ...
      <PaymentSheet />
    </Modal>
  );
}

Save Card sheet

...
import { useSumUp } from 'sumup-react-native-alpha';

export default function Screen() {
  const { initSaveCardSheet, presentSaveCardSheet } = useSumUp();

  useEffect(() => {
    initSDK();
  }, []);

  const initSDK = async () => {
    const res = await initSaveCardSheet({
      checkoutId: '...',
      customerId: '...'
    });

    console.log(res);
  };

  const onPress = async () => {
    const res = await presentSaveCardSheet();
    console.log(res);
  };

  return (
    <TouchableOpacity onPress={onPress}>
      <Text>Show the Save Card sheet</Text>
    </TouchableOpacity>
  );
}

Prefilling card details

Some card details can be prefilled. It can be used in the following way:

await initPaymentSheet({
  // ...
  defaultCardDetails: {
    cardHolderName: 'Some Name',
    saveCardForFutureUsage: false, // false is the default value
  },
});

await initSaveCardSheet({
  defaultCardDetails: {
    cardHolderName: 'Some Name',
  },
});

Saving a card for future usage in the process the payment flow

A card also can be saved when a user processes the payment. To enable it, the customer needs to be created. It can be done by the request that was described above.

Then create a new checkout with the created customerId. And provide customerId to initPaymentSheet function.

await initPaymentSheet({
  // ...
  customerId: '...',
});

Google Pay

To use Google Pay, first enable the Google Pay API by adding the following to the tag of your AndroidManifest.xml:

...

For more details, see Google Pay’s Set up Google Pay API for Android.

Then provide googlePay object in initPaymentSheet to init.

await initPaymentSheet({
  // ...
  googlePay: {
    isProductionEnvironment: false,
  },
});

NOTE: This is only used in the Payment sheet!

Apple Pay

NOTE: The backend doesn't process a payment with Apple Pay. An error message will be displayed after paying with it. It's a known issue and will be fixed!

Register for an Apple Merchant ID Obtain an Apple Merchant ID by registering for a new identifier on the Apple Developer website. Fill out the form with a description and identifier. Your description is for your own records and you can modify it in the future.

Then provide applePay object in initPaymentSheet to init.

await initPaymentSheet({
  // ...
  applePay: {
    merchantIdentifier: 'merchant.com.{{YOUR_APP_NAME}}',
  },
});

NOTE: This is only used in the Payment sheet!